README

此库提供了旨在简化编写 Laravel Blade 指令的方法，尤其是在尝试使用多个参数时。

此库使得编写如下代码成为可能

<?php

use Stillat\BladeDirectives\Support\Facades\Directive;
use Illuminate\Support\Str;

Directive::callback('limit', function ($value, $limit = 100, $end = '...') {
    return Str::limit($value, $limit, $end);
});

这允许您或您的指令用户编写如下 Blade 模板

{{-- Invoke our directive callback with default arguments --}}
@limit($myString)

{{-- Invoke our directive callback and specify a limit --}}
@limit($myString, 50)

{{-- Invoke our directive callback and change only the "end" parameter using named arguments --}}
@limit($myString, end: '---')

{{-- Invoke our directive callback with all parameters --}}
@limit($myString, 5, 'the cap')

{{-- Invoke our directive callback with all parameters using named arguments --}}
@limit($myString, end: ':o', limit: 5)

请注意，我们使用 callback 方法时，无需返回字符串或进行任何字符串操作。当使用 callback 方法时，Blade 指令将在幕后为您完成繁重的工作，您可以像编写其他 PHP 方法一样编写 Blade 指令。

编译方法

使用 compile 方法的最基本方式是这样的

<?php

use Stillat\BladeDirectives\Support\Facades\Directive;

Directive::compile('slugify', function ($value, $separator = '-') {
    return '<?php echo \Illuminate\Support\Str::slug($value, $separator); ?>';
});

这使得您的用户可以像这样编写 Blade

@slugify($title)
@slugify($title, '_')

使用 compile 方法编写的指令的开发者还可以使用命名参数

<?php

use Stillat\BladeDirectives\Support\Facades\Directive;

Directive::compile('limit', function ($value, $limit = 100, $end = '...') {
   return '<?php echo \Illuminate\Support\Str::limit($value, $limit, $end); ?>';
});

@limit($myString, end: '---')
@limit($myString, end: ':o', limit: 5)

这感觉更好，而且我们不必求助于容易出错的 explode 调用或 json_encode/json_decode。

安装

此库可以使用 Composer 安装

composer require stillat/blade-directives

编写指令

要开始，请将以下导入添加到您的 PHP 文件顶部

use Stillat\BladeDirectives\Support\Facades\Directive;

Directive 门面提供了三种不同的方法，您可以根据特定情况的需求进行选择

• params($name, callable $handler) - 类似于 Blade 的默认 directive 方法注册一个新的 Blade 指令。您将通过 $this->parameters 访问回调中的参数。您将只接收到作为第一个和唯一参数的原始输入字符串。
• make($name, callable $handler) - 注册一个支持多个参数的新 Blade 指令
• compile($name, callable $handler) - 注册一个支持多个参数的新 Blade 指令。此方法允许您返回一个 PHP 字符串，其中将自动为您替换变量

使用 make($name, callable $handler) 方法

make 方法允许您在指令的回调中指定（并接收）多个参数。您仍然负责手动构造最终用于 Blade 编译器的 PHP 字符串

<?php

use Stillat\BladeDirectives\Support\Facades\Directive;

Directive::make('greet', function ($name, $age) {
   return '<?php echo "Hello, ".'.$name.". ' - '. ".$age."; ?>";
});

以下 Blade

@greet('Hello!', 32)
@greet($varName, $ageVar)
@greet(' Escaped \' string!', '32')

产生以下编译输出

<?php echo "Hello, ".'Hello!'. ' - '. 32; ?>
<?php echo "Hello, ".$varName. ' - '. $ageVar; ?>
<?php echo "Hello, ".' Escaped \' string!'. ' - '. '32'; ?>

使用 compile($name, callable $handler) 方法

compile 方法允许您将 PHP 字符串作为指令处理程序的结果返回。内部编译器将努力替换变量引用，这使得您编写指令变得更加容易。

让我们使用 compile 方法重写 greet 指令

<?php

use Stillat\BladeDirectives\Support\Facades\Directive;

Directive::compile('greet', function ($name, $age) {
   return '<?php echo "Hello, $name - $age" ?>';
});

以下示例演示了使用指令参数的默认值

<?php

use Illuminate\Support\Facades\Blade;
use Stillat\BladeDirectives\Support\Facades\Directive;

Directive::compile('test', function ($data = [1, 2, 3]) {
   return '<?php foreach ($data as $value): ?>';
});

Blade::directive('endtest', function () {
    return '<?php endforeach; ?>';
});

以下 Blade

@test(['one', 'two', 'three'])

@endtest

产生类似的编译输出

<?php foreach (((['one', 'two', 'three']) ?? (array (
  0 => 1,
  1 => 2,
  2 => 3,
))) as $value): ?>

<?php endforeach; ?>

如果用户没有提供如下所示的任何值

@test

@endtest

编译输出将更改为

<?php foreach (((null) ?? (array (
  0 => 1,
  1 => 2,
  2 => 3,
))) as $value): ?>

<?php endforeach; ?>

转义变量名称

本节适用于 compile 方法。

"编译器" 实际上是一个美化的 "查找和替换"，可能会使您难以使用一个同时匹配您的参数名称的变量名称。为了转义变量名称，请在其前面加上 \ 字符

<?php

use Stillat\BladeDirectives\Support\Facades\Directive;

Directive::compile('escapeTest', function ($test, $anotherVar) {
   return '<?php echo 5 + ($test) / $anotherVar; ?> \$test \$anotherVar $anotherVar';
});

以下 Blade

@escapeTest(5 + 3 * 2, 15)

产生类似的编译输出

<?php echo 5 + (5 + 3 * 2) / 15; ?> $test $anotherVar 15

如您所见，所有匹配以 \ 字符开头的变量名称的内容都将为您转义。此外，字符串中所有变量的出现都将被替换，而不仅仅是 PHP 区域内的。

问题

由于这类项目的性质，可以保证它将以有趣的方式崩溃。在提交问题时，请尽可能提供详细信息以帮助重现问题，并清楚地解释期望的行为。

许可证

MIT许可证。见LICENSE.MD