README.md

Kirby Blade

Kirby Blade use Laravel illuminate/view 11.x package and compatible with Kirby 4.

This package enables Laravel Blade for your own Kirby applications.

Installation

composer require leitsch/kirby-blade

Caveat: Laravel and Kirby both define the e() helper function, but they do vastly different things. In Kirby, e() is basically just a shortcut for echo $condition ? $a : $b;. In Laravel, this function escapes HTML characters in a string. From Kirby 3.7 and up, you have to disable Kirby’s own e() helper by adding a single line of code to your index.php, before including the autoload.php file:

define('KIRBY_HELPER_E', false);

What is Blade?

According to Laravel Blade documentation is:

Blade is the simple, yet powerful templating engine that is included with Laravel. Unlike some PHP templating engines, Blade does not restrict you from using plain PHP code in your templates. In fact, all Blade templates are compiled into plain PHP code and cached until they are modified, meaning Blade adds essentially zero overhead to your application. Blade template files use the .blade.php file extension.

Usage

You can use the power of Blade like Layouts, Forms, Sub-Views, Components, Directives and your custom if statements.

All the documentation about Laravel Blade is in the official documentation.

Options

The default values of the package are:

Option	Default	Values	Description
leitsch.blade.templates	site/templates	(string)	Location of the templates
leitsch.blade.views	site/cache/views	(string)	Location of the views cached
leitsch.blade.directives	[]	(array)	Array with the custom directives
leitsch.blade.ifs	[]	(array)	Array with the custom if statements

All the values can be updated in the config.php file.

Templates

Default templates folder is site/templates directory or wherever you define your templates directory, but you can change this easily:

'leitsch.blade.templates' => '/theme/default/templates',

Views

All the views generated are stored in site/cache/views directory or wherever you define your cache directory, but you can change this easily:

'leitsch.blade.views' => '/site/storage/views',

Directives

By default, Kirby Blade comes with following directives:

@asset($path)
@csrf()
@css($path)
@dump($variable)
@e($condition, $value, $alternative)
@get($key, $default)
@gist($url)
@go($url, $code)
@h($string, $keepTags)
@html($string, $keepTags)
@js($path)
@image($path, $attr) // @image('forrest.jpg', 'url')
@kirbytag($type, $value, $attr)
@kirbytags($text, $data)
@kirbytext($text, $data)
@kirbytextinline($text)
@kt($text)
@markdown($text)
@option($key, $default)
@page($key, $attr) // @page('blog', 'title')
@param($key, $fallback)
@site($attr) // @site(title')
@size($value)
@smartypants($text)
@snippet($name, $data)
@svg($file)
@t($key, $fallback)
@tc($key, $count)
@tt($key, $fallback, $replace, $locale)
@u($path, $options)
@url($path, $options)
@video($url, $options, $attr)
@vimeo($url, $options, $attr)
@widont($string)
@youtube($url, $options, $attr)

But you can create your own:

'leitsch.blade.directives' => [
    'greeting' => function ($text)
    {
        return "<?php echo 'Hello: ' . $text ?>";
    },
],

Kirby Helpers Documentation:

https://getkirby.com/docs/reference/templates/helpers

If Statements

Like directives, you can create your own if statements:

'leitsch.blade.ifs' => [
    'logged' => function ()
    {
        return !!kirby()->user();
    },
],

After declaration, you can use it like:

@logged
    Welcome back {{ $kirby->user()->name() }}
@else
    Please Log In
@endlogged

Anonymous components

To define an anonymous component, you only need to place a Blade template within your site/templates/components directory. To render an alert component you have to define site/templates/components/alert.blade.php and the component can be rendered like:

<x-alert />

More about anonymous components in the official Laravel Blade documentation.

Class based components

For class based components, the app namespace must be added to your project composer.json.

{
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    }
}

The class must be placed in the site/components directory and will be autoloaded by the package.

A button class could look like:

<?php

namespace App\View\Components;

use Illuminate\Support\Facades\View;
use Illuminate\View\Component;

class Button extends Component
{
    public function render()
    {
        return View::make('components.button');
    }
}

The blade file of the button class should be placed in the site/templates/components/button.blade.php directory.

Hook

For use cases such as HTML minification, there's a custom hook for manipulating rendered HTML output:

# site/config/config.php

# For this example, we are using 'voku/html-min'
use voku\helper\HtmlMin;

return [
    # ...

    'hooks' => [
        'blade.render:after' => function (string $html): string {
            return (new HtmlMin())->minify($html);
        },
    ],

    # ...
];

Credits

• Kirby Blade by @afbora
• Torch by @mattstauffer
• Kirby Blade Repository by @beebmx