jakewhiteley/bladezero

9.52.16 2024-04-11 19:51 UTC

Requires

• php: ^7.4|^8.0
• illuminate/collections: v9.52.16
• league/commonmark: ^1.3|^2.0.2
• symfony/finder: ^5.4

Requires (Dev)

• doctrine/inflector: ^1.3
• mockery/mockery: ^1.2.3
• php-curl-class/php-curl-class: ^9.19
• phpunit/phpunit: ^8.5.19|^9.5.8
• ramsey/uuid: ^4.2.2
• symfony/console: ^5.0
• symfony/css-selector: ^5.0
• symfony/dom-crawler: ^5.0
• symfony/filesystem: ^5.0
• voku/portable-ascii: ^1.6

Suggests

• ext-mbstring: If you want to use Bladezero\Support\Str in your application.
• doctrine/inflector: If you want to use Bladezero\Support\Str pluralize methods in your application.
• ramsey/uuid: If you want to use Bladezero\Support\Str uuid methods in your application.

MIT

• Taylor Otwell
• Jake Whiteley

README

Import Laravel's Blade templating engine into non-Laravel applications the right way.

The wrong way

All other standalone versions of blade require ~16 dependencies, and run the Iluminate/Container and Illuminate/View packages in your app. This adds a ton of complexity to your app, and is considered a bad idea.

There are a few instances of packages rewriting the entire Blade engine from scratch, which creates the following typical issues:

• No longer able to rely on the Laravel docs means documentation is often incorrect.
• Features are often missing or implemented incorrectly.

The *right* way

BladeZero is a direct split from laravel/framework and only includes files directly needed to compile Blade templates - no Container, no View, no fuss.

95% of the code is a perfect match for the code written by Taylor Otwell and the Laravel contributors, meaning every single Blade feature is supported exactly as it should be.

Installation

Use Composer:

composer require jakewhiteley/bladezero

Usage

After pulling the package down, you need to provide the full paths to your templates and cache directories:

use Bladezero\Factory;

$templatesPath = realpath('./files');
$cachePath = realpath('./cache');

$blade = new Factory($templatesPath, $cachePath);

// Make and output a view with some data
echo $blade->make('example', ['title' => 'It Works!']);

Extending BladeZero

As the BladeZero\Factory class is just a modifed Illuminate\View\Factory, all the methods you would expect are available:

// Add a new templates directory
$blade->addLocation(realpath('./shared/components'));

// Add a namespace
$blade->addNamespace('shared', realpath('./shared/components'));

// Register a component
$blade->component('components.alert', 'alert');

// Register a custom directive
$blade->directive('foo', function($expression) {
    return "<?php echo 'foo' . $expression; ?>";
});

// Register a custom if directive
$blade->if('foo', function($bar) {
    return $bar === 'foobar';
});

// Register a custom template alias
$blade->include('php.raw', 'foo');

// Add shared data
$blade->share($key, $value = null);

BladeZero supports all the Blade features you know such as custom directives, custom if statements, components.

BladeZero lets you write your own View classes as this package is to provide the Blade rendering engine for your own projects - not include half of Laravel. In order to facilitate this, some functionality you would access vie the View facade is also available; such as making data available to all views, and view namespaces

Differences

Even though the Blade compiler is 100% the same as it's Laravel twin, your application is not.

Because of this, BladeZero provides methods to easily get the Laravel-specific features of Blade working in your framework:

@csrf

Use the setCsrfHandler method to specify how to provide the @csrf() directive with the correct token:

$blade->setCsrfHandler(function(): string {
    return MySessionClass::getUserToken();
});

@auth

Set how your application handles auth directives such as @auth, @elseauth, and @guest:

$blade->setAuthHandler(function(string $guard = null): bool {
    return MyUserClass::currentUserIs($guard);
});

@can

Set how your application handles permissions directives such as @can, @cannot, and @canany:

$blade->setcanHandler(function($abilities, $arguments = []): bool {
    return MyUserClass::currentUserCan($abilities, $arguments);
});

@inject

If your application uses a dependency injection Container, sepcify how services should be resolved via @inject:

$blade->setInjectHandler(function(string $service) {
    return MyContainer::resolveService($service);
});

@error

Allwos you to provide how the @error directive should work.

Your callback should return the first error string or false:

$blade->setErrorHandler(function(string $key) {
    return MyErrorBag::getErrorMessageFor($key);
});