An easier way to define custom Blade directives.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
src
tests
.editorconfig
.gitattributes
.gitignore
.scrutinizer.yml
.styleci.yml
.travis.yml
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE.md
README.md
UPGRADING.md
composer.json
phpunit.xml.dist

README.md

Laravel Blade Helper

Latest Version on Packagist Build Status Code Quality Code Coverage Total Downloads License

An easier way to define custom Blade directives.

When creating new custom Blade directives using the Blade::directive(…) method, the only parameter made available to manipulate is the expression passed through from the .blade.php file as a raw string. It seems to be rare that developers actually parse the contents of the expression itself within the directive, opting instead to pass the entire expression as arguments to a helper function or a method on another class. For example:

BladeHelper::directive('uppercase', function($expression) {
    return "<?php echo strtoupper($expression); ?>";
});

As this seems to be the most common use case, this package attempts to help make these helper functions that little bit easier to define without the boilerplate of returning the string or having to consider what an expression may be when creating a directive.

💾 Installation

You can install the package with Composer using the following command:

composer require imliam/laravel-blade-helper:^1.0.0

📝 Usage

The BladeHelper object is bound to Laravel's service container with the name blade.helper and can be used by resolving that. A Facade is also made available for convenience. To define a helper, the ->directive(…) method is used:

app('blade.helper')->directive(…);

\ImLiam\BladeHelper\Facades\BladeHelper::directive(…);

This method accepts two arguments; the first is the name of the directive, and the second is the function that the directive should call:

// Define the helper directive
BladeHelper::directive('uppercase', 'strtoupper');

// Use it in a view
@uppercase('Hello world.')

// Get the compiled result
<?php echo strtoupper('Hello world.'); ?>

// See what's echoed
"HELLO WORLD."

If no second argument is supplied, the directive will attempt to call a function of the same name:

// Define the helper directive
BladeHelper::directive('join');

// Use it in a view
@join('|', ['Hello', 'world'])

// Get the compiled result
<?php echo join('|', ['Hello', 'world']); ?>

// See what's echoed
"Hello|world"

The second argument can also take a callback. The advantage of a callback here over the typical Blade::directive(…) method Laravel offers is that the callback given can have specific parameters defined instead of just getting raw expression as a string. This brings several advantages to the process of creating a Blade helper directive:

  • Type hint the arguments for the callback
  • Manipulate and use the individual arguments when the directive is called, instead of the raw expression as a string
  • Define a directive without having to only use it as a proxy to a helper function or class in another part of the application
// Define the helper directive
BladeHelper::directive('example', function($a, $b, $c = 'give', $d = 'you') {
    return "$a $b $c $d up";
});

// Use it in a view
@example('Never', 'gonna')

// Get the compiled result
<?php echo app('blade.helper')->getDirective('example', 'Never', 'gonna'); ?>

// See what's echoed
"Never gonna give you up"

By default, all of the helper directives will echo out their contents to the view when used. This can be disabled by passing false as the third argument:

// Define the helper directive
BladeHelper::directive('log', null, false);

// Use it in a view
@log('View loaded…')

// Get the compiled result
<?php log('View loaded…'); ?>

// Nothing is echoed

One example of a custom Blade helper is to wrap around FontAwesome 4 icons to make it more convenient to add alternate text for the sake of accessibility:

// Define the helper directive
Blade::directive('fa', function(string $iconName, string $text = null, $classes = '') {
    if (is_array($classes)) {
        $classes = join(' ', $classes);
    }

    $text = $text ?? $iconName;

    return "<i class='fa fa-{$iconName} {$classes}' aria-hidden='true' title='{$text}'></i><span class='sr-only'>{$text}</span>";
});

// Use it in a view
@fa('email', 'Envelope')

Testing

composer test

🔖 Changelog

Please see the changelog file for more information on what has changed recently.

⬆️ Upgrading

Please see the upgrading file for details on upgrading from previous versions.

🎉 Contributing

Please see the contributing file and code of conduct for details on contributing to the project.

🔒 Security

If you discover any security related issues, please email liam@liamhammett.com instead of using the issue tracker.

👷 Credits

♻️ License

The MIT License (MIT). Please see the license file for more information.