Compile and save files from the command line using Laravel's blade engine.

You may install the binary via composer globally:

composer global require surgiie/blade-cli

Then be sure the global composer packages path is executable:

Note The pctnl extension is recommended to be installed, otherwise install with composer global require surgiie/blade-cli --ignore-platform-reqs

# may vary on systems:
export PATH=~/.config/composer/vendor/bin:$PATH

You may download a tag/release from releases and make available in $PATH:

# in ~/.bashrc or equivalent
PATH=/usr/local/bin/blade-cli:$PATH

Install dependencies:

composer install

Confirm is executable:

blade

Available for bash, you may optionally source the completion script for terminal completion:

source <(curl -s https://raw.githubusercontent.com/surgiie/blade-cli/master/completion)

Lets work through an example, given this file exists in your current directory (person.yml):

name: {{ $name }}
relationship: {{ $relationship }}
favorite_food: {{ $favoriteFood }}
@if($includeAddress)
address: "123 example lane"
@endif

You may render that file as follows:

blade render ./person.yml \
                --name="Bob" \
                --relationship="Uncle" \
                --favorite-food="Pizza" \
                --include-address

This will render and save the file to the same directory as a file named person.rendered.yml

All files will get saved to the same directory as the file being rendered as <filename>.rendered.<extension> or simply <filename>.rendered. This is to avoid overwriting the file you are rendering. If you wish to save the file as a custom file name or change the directory, use the --save-to option to specify a file path to write the file to:

blade render ./person.yml \
            ...
            --save-to="/home/bob/custom-name.yml"

Note - The blade class will attempt to automatically ensure the parent directories exist if it can write them otherwise an error is thrown due to lack of permissions.

There are 3 options for passing variable data to your files being rendered, in precedence order from lowest to highest :

1. Using yaml files via the --from-yaml option to pass a path to a yaml file. This maybe passed multiple times to load from many files.

2. Using json files via the --from-json option to pass a path to a json file. This maybe passed multiple times to load from many files.

3. Using env files via the --from-env option to pass a path a .env file. This maybe passed multiple times to load from many files.

4. Lastly as you saw in the earlier example above, through arbitrary command line options to the render command. --example-var=value

Your env, yaml, and json file keys can be defined in any naming convention you prefer, but your actual variable references MUST be camel case. This is because php doesnt support kebab cased variables and since this is the format used command line options, all variables will automatically get converted to camel case. For example, if you pass an option or define a variable name in your files in any of these formats: favorite-food, favoriteFood, or favorite_food, the variable for that option should be referenced as $favoriteFood in your files.

These are the current supported way to pass variables for different types/purposes:

Use single option key/value format for passing variables for single string values:

--foo=bar --bar=baz

For array variables, just pass the option more than once:

--names=Steve --names=Ricky --names=Bob

For boolean true variables, just pass the option with no value:

--should-do-thing

Note Since variable options are dynamic the "negate/false" options are not supported. Instead do something like this in your files {{ $shouldDoSomething ?? false }} to default to false and then use true options to "negate" the value.

If you try to render a file that already exists an exception will be raised, you may consider force write via the --force flag.

blade render ./person.yml \
                --name="Bob" \
                --relationship="Uncle" \
                --favorite-food="Pizza" \
                --include-address \
                --force # force overwrite person.rendered.yml if it already exists.

If you would like to output the contents of a rendered file to your terminal and not actually save the file, you may add the --dry-run flag when rendering a single file:

blade render example.yaml --some-var=example --dry-run

This will echo/output the rendered contents of example.yaml only.

You may also pass the path to a directory instead of a single file. This might be useful if you like to group template files in a directory and want to render them all with a single command:

blade render ./templates --save-dir="/home/bob/templates" --some-data=foo

Note This will prompt you for confirmation, you may skip confirmation by adding the --force flag.

Note When rendering an entire directory the --save-dir option is required so that the cli exports all rendered files to a separate directory than the one being processed. The directory the files get saved in will mirror the directory structure of the directory being processed. In the above example /home/bob/templates will have a directory structure that matches ./templates.

If you wish to use the api directly, you may utilize the Blade class directly in your apps:

use Surgiie\BladeCLI\Blade;
use Illuminate\Container\Container;
use Illuminate\Filesystem\Filesystem;

$blade = new Blade(
    container: new Container,
    filesystem: new Filesystem,
    filePath: '/path/to/file/to/render',
    options: [
        'force'=> true, // force overwrite existing rendered file
        'save-to'=>'save-to' // optional file path to save file as.
    ]
);

// render and save the file with this data/vars
$contents = $blade->render([
    'var'=>'example'
]);

// you may prevent the file from being saved, by passing false to the 2nd argument of the render method
// this is useful if you wish to process the contents of the rendered file yourself and do specific custom tasks.
$contents = $blade->render(
    ['var'=>'example'],
    false
);

Contributions are always welcome in the following manner:

• Issue Tracker
• Pull Requests
• Discussions

The project is licensed under the MIT license.