README

本包为 Laravel Blade 模板引擎提供附加指令。其中指令包括功能齐全的部分视图、翻译和 dot.js 构造。

安装

将 require 添加到 composer.json 并运行 composer update

"require": {
    "swayok/laravel-blade-directives": "~1.0",
}

配置

Laravel 5.6+ 的服务提供者

通过包自动发现自动添加。

Laravel < 5.6 的服务提供者

将 \LaravelBladeDirectives\LaravelBladeDirectivesServiceProvider::class 添加到你的 config/app.php 中的 providers 数组

快捷键

@breakpoint 
// add breakpoint to view (allows you to debug compiled views)

@string($id, $parameters = [], $locale = null)
@trans($id, $parameters = [], $locale = null)
// {{ trans($id, $parameters, $locale) }}

@html($id, $parameters = [], $locale = null)
@unescaped($id, $parameters = [], $locale = null)
// {!! trans($id, $parameters, $locale) !!}

@key($array, $key, $default, $escaped = true)
// {{ array_get($array, $key, $default) }} - when $escaped === true
// {!! array_get($array, $key, $default) !!} - when $escaped === false

Examples:

@string('frontend.footer', ['year' => 2019], 'en')
@trans('frontend.footer', ['year' => 2019])
@html('frontend.lang.' . app()->locale())
@unescaped('frontend.app_name')

@key($settings, 'language', 'en') 
// {{ array_get($settings, 'language', 'en') }}
@key($settings, 'language', 'en', false)
// {!! array_get($settings, 'language', 'en') !!}

部分视图

部分视图的背后的想法是可以多次在单个 blade 模板中使用子模板，而不需要使用需要创建视图文件的 @view() 指令。有时你不需要为像表格行这样的简单模板创建单独的视图文件。部分视图还有助于使大型模板更简洁。

声明部分视图

输出部分视图

@partial('name')
    <div>{{ $var1 }}</div>
@endPartial

结果

@yieldPartial('name', ['var1' => 'this is partial'])
@yieldpartial('name', ['var1' => 'this is another partial'])

注意：所有指令都具有 camelCase 和小写版本

<div>this is partial</div>
<div>this is another partial</div>

dot.js 指令

在 blade 模板中使用 dot.js 插入是一个痛点。你需要在每个 dot.js 插入前添加 @，而且你无法在插入中插入 PHP 代码。模板有时会变得一团糟。

这个指令的想法是使包含 dot.js 插入的 blade 模板更干净、更直观。此外，还必须有可能在指令中插入一些 PHP 代码。

简单插入

复杂插入带有 PHP 代码

@jsEcho(it.value)
// {{= it.value }}
@jsecho(it.value || 'default')
// {{= it.value || 'default' }}

@jsEchoEncoded(it.value)
// {{! it.value }}
@jsechoencoded(it.value || "default")
// {{! it.value || "default" }}

@jsEval(it._some_name = 'value')
// {{ it._some_name = 'value' }}
@jseval(it._some_name = "value")
// {{ it._some_name = "value" }}

@jsIf(it.value)
// {{? it.value }}
@jsif(it.value === 'example')
// {{? it.value === 'example' }}

@jsIfSimple(it.value)
// {{? it.value }}
@jsifsimple(it.value === 'example')
// {{? it.value === 'example' }}

@jsElseIf(it.value)
// {{?? it.value }}
@jselseif(it.value === 'example')
// {{?? it.value === 'example' }}

@jsElseIfSimple(it.value)
// {{?? it.value }}
@jselseifsimple(it.value === 'example')
// {{?? it.value === 'example' }}

@jsElse
@jselse
// {{??}}

@jsEndIf
@jsendif
// {{?}}

@jsForEach(it.array as key => value)
// {{~ it.array :value:key }}
@jsforeach(it.array as value)
// {{~ it.array :value }}

@jsEndForEach
@jsendforeach
// {{~}}

@jsPartial(partial_name_without_spaces)
@jspartial(partial_name_without_spaces)
// {{##def.partial_name_without_spaces:

@jsEndPartial
@jsendpartial
// #}}

@jsEchoPartial(partial_name_without_spaces)
@jsechopartial(partial_name_without_spaces)
// {{#def.partial_name_without_spaces}}

PHP 代码必须在 dot.js 指令中以 `. 开始并以 .` 结束（引号是键盘上的波浪号 ~ 按钮上的引号，称为 backtick）。

使用反引号允许使用正常的引号和双引号，而不会因引号转义不正确而导致问题。如果你使用 PHP Storm，你可以配置反引号的代码样式，使其与其他引号不同，并以独特的方式显示 dot.js 指令（配置在下一节中）。

示例

支持 PHP 代码的指令

$phpVar = 'var_string'
SOME_CONSTANT = 'constant_string'
$phpNumber = 5

@jsIf(it.value === "` . $phpVar . `")
// {{? it.value === "var_string" }}
// Resulting php code in compiled template is: <?php echo '@{{? it.value === "' . ($phpVar) . '" }}'; ?>

@jsIf(it.value === '` . $phpVar . `')
// {{? it.value === 'var_string' }}
// Resulting php code in compiled template is: <?php echo '@{{? it.value === \'' . ($phpVar) . '\' }}'; ?>

@jsif(it.value === "` . SOME_CONSTANT . `")
// {{? it.value === "constant_string" }}

@jsIf(it.value >= ` . ($phpNumber - 1) . ` && it.value <= ` . ($phpNumber + 1) . `)
// {{? it.value >= 4 && it.value <= 6}}

jsEcho/jsecho

• jsEchoEncoded/jsechoencoded
• jsEval/jseval
• jsIf/jsif
• jsElseIf/jselseif
• jsElseIf/jselseif

不支持 PHP 代码的指令

• jsIfSimple/jsifsimple
• jsElseIfSimple/jselseifsimple
• jsForEach/jsforeach
• jsPartial/jspartial
• jsEchoPartial/jsechopartial
• 不允许参数的其他指令（如 jsEndIf、jsEndForEach）

PHP Storm 配置（Blade 指令）

打开 设置 > 语言 & 框架 > PHP > Blade。取消选择 使用默认设置。打开 指令 选项卡。

每个指令都有以下输入

• 名称
• 是否有参数
• 前缀
• 后缀

注意：具有相同配置的指令会被分组在“名称”中 - 您需要为每个指令名称创建一个记录。

Names: string, trans, html, unescaped
Has parameter: true
Prefix: <?php echo trans(
Suffix: ); ?>

Names: key
Has parameter: true
Prefix: <?php $fn = function(array $array, $key, $default = null, bool $escaped = true) {} ; $fn(
Suffix: ); ?>

Names: partial
Has parameter: true
Prefix: <?php $str =
Suffix: ); ?>

Names: yieldPartial, yieldpartial
Has parameter: true
Prefix: <?php $fn = function(string $partialName, array $partialData = []) {}; $fn(
Suffix: ); ?>

Names: breakpoint, endPartial, endpartial
Has parameter: false

Names: jsEcho, jsEchoEncoded, jsEval, jsForEach, jsIf, jsElseIf, jsIfSimple, jsElseIfSimple, jsPartial, jsEchoPartial 
Has parameter: true
Prefix: <?php echo `
Suffix: `; ?>

Names: jsecho, jsechoencoded, jseval, jsforeach, jsif, jselseif, jsifsimple, jselseifsimple, jspartial, jsechopartial
Has parameter: true
Prefix: <?php echo `
Suffix: `; ?>

Names: jsElse, jsEndIf, jsEndForEach, jselse, jsendif, jsendforeach, jsEndPartial, jsendpartial
Has parameter: false

PHP Storm 配置（指令颜色）

打开 设置 > 编辑器 > 代码颜色方案 > Blade。这里有趣的参数包括

• 指令
• 文本块分隔符

我为两者都添加了背景色，以便在 Blade 模板中清晰地看到指令。

打开 设置 > 编辑器 > 代码颜色方案 > PHP。

这里有趣的参数是 Shell 命令。这是 PHP 中很少使用的功能，但将有助于将 dot.js 指令与常规 Blade 指令区分开来。只需添加一些背景色。这将用特定的背景色显示 dot.js 指令内的参数。我个人喜欢这个功能，因为它使常规指令和 dot.js 指令在视觉上有所不同。