Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stillat/blade-directives
A package that makes writing Laravel Blade directives easier when requiring multiple parameters.
https://github.com/stillat/blade-directives
Last synced: 2 days ago
JSON representation
A package that makes writing Laravel Blade directives easier when requiring multiple parameters.
- Host: GitHub
- URL: https://github.com/stillat/blade-directives
- Owner: Stillat
- License: mit
- Created: 2021-10-23T22:09:22.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-02-01T14:44:59.000Z (almost 2 years ago)
- Last Synced: 2024-04-23T15:21:09.947Z (9 months ago)
- Language: PHP
- Size: 17.6 KB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Blade Directives
This library provides utility methods that aim to make writing Laravel Blade directives easier, especially when attempting to use multiple parameters.
This library makes it possible to write code like this:
```php
';
});
```
Which allows your users to write Blade like this:
```blade
@slugify($title)
@slugify($title, '_')
```
Developers using directives written using the `compile` method can also use named arguments:
```php
';
});
```
```blade
@limit($myString, end: '---')
@limit($myString, end: ':o', limit: 5)
```
That just feels better, and we didn't have to resort to error-prone `explode` calls, or `json_encode/json_decode`.
## Installation
This library can be installed with Composer:
```
composer require stillat/blade-directives
```
## Writing Directives
To get started, add the following import to the top of your PHP file:
```php
use Stillat\BladeDirectives\Support\Facades\Directive;
```
The `Directive` façade provides three different methods that you can choose from depending on what you require for a given situation:
* `params($name, callable $handler)` - registers a new Blade directive similarly to Blade's default `directive` method. You will have access to the parameters within the callback through `$this->parameters`. You will only receive the raw input string as the first, and only argument.
* `make($name, callable $handler)` - registers a new Blade directive with support for multiple parameters
* `compile($name, callable $handler)` - registers a new Blade directive with support for multiple parameters. This method allows you to return a PHP string, which will have variables replaced for you automatically
### Using the `make($name, callable $handler)` Method
The `make` method allows you to specify (and receive) multiple parameters on your directive's callback. You are still responsible for manually constructing the final PHP string for the Blade compiler:
```php
";
});
```
The following Blade:
```blade
@greet('Hello!', 32)
@greet($varName, $ageVar)
@greet(' Escaped \' string!', '32')
```
Produces the following compiled output:
```php
```
### Using the `compile($name, callable $handler)` Method
The `compile` method allows you to return a PHP string as the result of your directive's handler. The internal compiler will work to replace the variable references with the required compiled output, which makes it much easier for you to write your directive.
Let's rewrite the `greet` directive using the `compile` method:
```php
';
});
```
The following example demonstrates using default values for directive parameters:
```php
';
});
Blade::directive('endtest', function () {
return '';
});
```
The following Blade:
```blade
@test(['one', 'two', 'three'])
@endtest
```
Produces compiled output similar to the following:
```php
1,
1 => 2,
2 => 3,
))) as $value): ?>
```
If the user did not supply any values like so:
```blade
@test
@endtest
```
The compiled output would change to:
```php
1,
1 => 2,
2 => 3,
))) as $value): ?>
```
## Escaping Variable Names
This section applies to the `compile` method.
The "compiler" is effectively a glorified "find and replace", and can make it difficult to use a variable name if it also matches one of your parameter names. To escape a variable name, precede it with the `\` character:
```php
\$test \$anotherVar $anotherVar';
});
```
The following Blade:
```blade
@escapeTest(5 + 3 * 2, 15)
```
Produces compiled output similar to the following:
```php
$test $anotherVar 15
```
As you can see, anything that matches a variable name preceded by the `\` character is escaped for you. Additionally, all occurrences of the variable are replaced in the string, not just within PHP areas.
## Issues
Due to the nature of projects like this, it is guaranteed that it will break in interesting ways. When submitting issues, please include as much information as possible to help reproduce the issue, and a clear explanation of desired behavior.
## License
MIT License. See LICENSE.MD