Use Laravel's blade engine as a CLI for rendering files.

Last update: Jun 21, 2022

Blade CLI

tests

Use Laravel's blade engine as a CLI for rendering files.

Introduction

This package customizes and extends several of the Illuminate\View classes used by the blade engine to be able to use simple blade features/directives (i.e @if, @include, @foreach, etc.) on files. That said, the more advanced features of the engine are out of scope of what this package was meant for and may not be supported.

Installation

Download specific tag version 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

Or if you want to use the api directly as a package, you can install with composer:

composer require surgiie/blade-cli

and use the class directly

use 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-directory'=>'save-to-dir' // optional directory to save rendered file to. Default is the directory the file is in.
    ]
);

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

CLI Completion

You may optionally source the provided completion script for bash completion:

source /usr/local/bin/blade-cli/completion

Use

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 person.rendered.yml

Custom Save Directory

All files will get saved to the same directory as the file being rendered as <filename>.rendered.<extension> or simply <filename>.rendered if the file does not have an extension when you do not provide a custom directory to save the rendred file to. This is to avoid overwriting the file you are rendering. If you wish to save to a custom directory use the --save-directory option to specify a directory to write the file to:

php blade render ./person.yml \
                --name="Bob"
                --relationship="Uncle"
                --favorite-food="Pizza"
                --include-address
                --save-directory="rendered-files/"

The blade class will attempt to automatically ensure the directory exists if it can write to it. In the above example the the result of ./person.yml would get written to ./rendered-files/person.yml.

Variable Data

There are 2 options for passing variable data to your files being rendered:

  1. As you saw in the earlier example above, the first method is through options to the render command. --example-var=value

  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. Note that options take precedence over the data loaded from json files.

Variable Naming Convention

Options or keys in your json file can be defined in any naming convention you prefer, but your actual variable reference should be camel case. This is because php doesnt support kebab cased variables which is often the format for command line options. That said, since camel case is usually standard, that is the format we decided to stick with. Your options will automatically get converted to data using camel case. To clarify a bit:

Either one of these option formats can be used --favorite-food, --favoriteFood, --favorite_food to reference a {{ $favoriteFood }} variable in your file.

Variable Types

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

String/Single Value Variables

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

--foo=bar --bar=baz

Array Value Variables

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

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

True Boolean Value Variables

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.

Force write

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

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

Processing an entire directory of files

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:

php blade render templates/ --some-data=foo

Note This will prompt you for confirmation.

Force process directory

You may skip confirmation of rendering a directory's files with the --force flag:

php blade render templates/ --some-data=foo --force

Custom Directory for directory files:

By default, files will get saved to the same directory the file being rendered is in, as seen earlier, you may specify a custom directory to save rendered files in with the same --save-directory option:

php blade render templates/ --some-data=foo --save-directory="/home/bob/templates/"

Note When using a custom directory to save to, the directory specified will have files saved to mirror the directory being processed. In this example /home/bob/templates/ will have a directory structure that matches templates/.

Unit Testing

If utilizing the \BladeCLI\Blade class directly in an app, the following methods maybe utilized to make unit testing easier:

<?php

// turns on testing mode and will write files into the given testing directory.
Blade::fake('./testing-directory');

// write ./testing-directory/example.yaml to test render call on
Blade::putTestFile('example.yaml', 
<<<EOL
name: {{ \$name }}
favorite_food: {{ \$favoriteFood }}
pets:
    @foreach(\$dogs as \$dog)
    - {{ \$dog }}
    @endforeach
contact_info:
    phone: 1234567890
    @if(\$includeAddress)
    street_info: 123 Lane.
    @endif
EOL
);

// generates a path to the testing directory, ie ./testing-directory/example.yaml
Blade::testPath('example.yaml');

// asserts that file exists in ./testing-directory/example.rendered.yaml
Blade::assertRendered('example.rendered.yaml');

// assert the rendered file exists and matches the expected content
Blade::assertRendered('example.rendered.yaml', 
<<<EOL
name: Bob
favorite_food: Pizza
pets:
    - Rex
    - Charlie
contact_info:
    phone: 1234567890
    street_info: 123 Lane.
EOL);

// removes current testing directory and turns off testing mode
Blade::tearDown();

GitHub

https://github.com/surgiie/blade-cli
You might also like...

Blade is a simple, yet powerful templating engine provided for the Slim Framework

slim-blade Blade is the default template engine of Laravel. The main advantage of Blade is template inheritance whilst using plain PHP. This package a

May 24, 2021

A package that uses blade templates to control how markdown is converted to HTML inside Laravel, as well as providing support for markdown files to Laravel views.

A package that uses blade templates to control how markdown is converted to HTML inside Laravel, as well as providing support for markdown files to Laravel views.

Install Install via composer. $ composer require olliecodes/laravel-etched-blade Once installed you'll want to publish the config. $ php artisan vendo

Jul 5, 2021

A package to easily make use of Iconic icons in your Laravel Blade views.

A package to easily make use of Iconic icons in your Laravel Blade views.

Blade Iconic A package to easily make use of Iconic icons in your Laravel Blade views. For a full list of available icons see the SVG directory. Iconi

Jun 3, 2022

A package to easily make use of Simple Icons in your Laravel Blade views.

A package to easily make use of Simple Icons in your Laravel Blade views.

Blade Simple Icons A package to easily make use of Simple Icons in your Laravel Blade views. For a full list of available icons see the SVG directory.

Jan 17, 2022

Cagilo - a set of simple components for use in your views Laravel Blade.

Cagilo - a set of simple components for use in your views Laravel Blade. Official Documentation Documentation for Cagilo can be found on its we

Jul 1, 2022

Use Blade templates without the full Laravel framework

blade Use Laravel Blade templates as a standalone component without the full Laravel framework Full documentation is available at http://duncan3dc.git

Apr 22, 2022

A package to easily make use of SVG icons in your Laravel Blade views.

A package to easily make use of SVG icons in your Laravel Blade views.

Blade Icons A package to easily make use of SVG icons in your Laravel Blade views. Originally "Blade SVG" by Adam Wathan. Turn... !-- camera.svg --

Jun 29, 2022

A package to easily make use of Iconsax in your Laravel Blade views.

A package to easily make use of Iconsax in your Laravel Blade views.

Blade Iconsax A package to easily make use of Iconsax in your Laravel Blade views. This package contains 1.000 icons in 6 diferent styles, a total of

May 18, 2022

Bunny CLI - Replicate and store your files to the edge!

Bunny CLI - Replicate and store your files to the edge! What is Bunny CLI? Bunny CLI is a tool for the console to upload frontend frameworks such as A

Apr 18, 2022
Comments
  • 1. Improve test file write and add test for directory render.

    • Improve Blade::putTestFile to mkdir recursively for nested file values.
    • Adds test for render command call on a directory.
    • Cleanup exception handling in RenderCommand.
    Reviewed by surgiie at 2022-06-14 04:50
  • 2. Testing Refactors & Utilize SplFileInfo for file metadata needs.

    • Reworks test suite to utilize new Blade testing helpers. Blade::assertRendered|putTestFile|testPath etc.
    • Remove deriveFileMetadata and utilize SplFileInfo object for the file being rendered.
    • Remove NormalizesPaths trait, SplFileInfo does this for paths.
    • General code cleanups.
    • Readme cleanups & document unit testing helpers
    • Remove unneeded extended code
    • Add CouldntWriteFileException
    • Regenerate completion script and increment to 0.1.0 for release.
    Reviewed by surgiie at 2022-06-13 06:39
Use Laravel's Blade templating engine outside of Laravel.

Use Laravel's Blade templating engine outside of Laravel. This package provides a standalone version of Laravel's Blade templating engine for use outs

Jun 8, 2022
Composer package which adds support for HTML5 elements using Laravels Form interface (e.g. Form::date())

Laravel HTML 5 Inputs Composer package which adds support for HTML5 elements by extending Laravel's Form interface (e.g. Form::date()) Adds support fo

Oct 13, 2020
A package to flash multiple messages using Laravels default session message flashing system
A package to flash multiple messages using Laravels default session message flashing system

Flash multiple advanced messages with both text, messages and links An opinionated solution for flashing multiple advanced messages from the backend a

Jan 18, 2022
Adds a way to write php and run it directly in Laravels' Artisan Tinker.
Adds a way to write php and run it directly in Laravels' Artisan Tinker.

Adds a way to write php in PhpStorm/IDEA and run it directly as if through laravel artisan tinker - allowing you to quickly run a piece of code with a

Jun 25, 2022
Blade UI Kit is a set of renderless components to utilise in your Laravel Blade views
Blade UI Kit is a set of renderless components to utilise in your Laravel Blade views

Blade UI Kit is a set of renderless components to utilise in your Laravel Blade views. In all essence, it's a collection of useful utilities, connecting the dots between different parts of the TALL stack. It was made for Blade, Laravel's powerful templating engine.

Jun 29, 2022
A Laravel package that allows you to use multiple ".env" files in a precedent manner. Use ".env" files per domain (multi-tentant)!
A Laravel package that allows you to use multiple

Laravel Multi ENVs Use multiple .envs files and have a chain of precedence for the environment variables in these different .envs files. Use the .env

Jun 23, 2022
A Laravel Code Generator based on your Models using Blade Template Engine
A Laravel Code Generator based on your Models using Blade Template Engine

Laravel Code Generator is a PHP Laravel Package that uses Blade template engine to generate code for you. The difference between other code generators

Jun 16, 2022
Snippets for blade template engine

Blade Snippets for Sublime Text Blade is a simple, yet powerful templating engine provided with Laravel PHP framework. These snippets works with blade

Oct 4, 2021
This package adds syntax definitions for the Laravel Blade engine.
This package adds syntax definitions for the Laravel Blade engine.

Laravel Blade Highlighter This package adds syntax definitions for the Laravel Blade engine. Works with various Sublime Text version, for older/specif

May 16, 2022
A general-purpose parser for Laravel's Blade templating engine.

A general-purpose parser for Laravel's Blade templating engine. This is where your description should go. Try and limit it to a paragraph or two. Cons

Feb 18, 2022