README

Laravel Blade @expects

重要：此包处于早期阶段，并未对所有支持的PHP或Laravel版本进行广泛测试。请谨慎使用...

动机

Blade模板 很棒，但缺乏定义其工作所需变量的好方法。在普通模板中，您必须检查变量是否已设置并为它设置默认值。

以这个例子为例

<?php

if(!isset($type))
{
    $type = 'boxed';
}

?>
<div class="component component-{{ $type }}">
    @if($type == 'big')
        <h1 class="component-title">{{ $object->title }}</h1>
    @endif
    
    <div class="component-content component-content-{{ $size ?? 'medium' }}">
        {{ $object->content }}
    </h1>
</div>

您必须检查某些变量是否已定义，并为其他一些变量设置默认值。一个没有使用此模板的同事可能会问：

• 为了使模板工作，必须定义哪些变量？
• 未定义变量的默认值是什么？
• $object 实例必须是哪个类？
• 如果 $object 不是正确类的实例会发生什么？

在大模板中，有很多复杂的HTML代码与CSS框架类和JS框架属性混合在一起，猜测这些信息可能会相当困难。为了解决这些问题，此包添加了一个简单的 @expects 指令来定义视图所期望的变量。

用法

@expects(\App\Object $object, string $type, string $size = 'medium')

<div class="component component-{{ $type ?: 'embedded' }}">
    @if($type == 'big')
        <h1 class="component-title">{{ $object->title }}</h1>
    @endif
    
    <div class="component-content component-content-{{ $size' }}">
        {{ $object->content }}
    </h1>
</div>

将其用作phpDoc块的包装器，作用相同，并允许IDE（如phpStorm）对变量进行类型提示

@expects

/**
 * Let's define the variables and its types
 *
 * @var \App\Object $object Object description
 * @var string|null $type   Type description
 * @var string      $size   Size description (default: medium) 
 */
 
 @endexpects
 
<div class="component component-{{ $type ?: 'embedded' }}">
    @if($type == 'big')
        <h1 class="component-title">{{ $object->title }}</h1>
    @endif
    
    <div class="component-content component-content-{{ $size' }}">
        {{ $object->content }}
    </h1>
</div>

两种方式都强制 $object 被定义为 \App\Object 实例，$type 为字符串，如果未设置，$size 将采用 medium 值。

可以使用多行语法调用指令以改善可读性

@expects(
    \Very\Very\Very\Long\Namespace\Classes\FirstClass  $class1, 
    \Very\Very\Very\Long\Namespace\Classes\SecondClass $class2,
    \Very\Very\Very\Long\Namespace\Classes\ThirdClass  $class3 
)

目标是让任何与模板一起工作的程序员都能立即知道哪些变量对于其操作是必要的，以及其类型和默认值。

PHP标签

您可能还需要禁用模板中的PHP标签。这将防止使用控制结构或声明变量，迫使使用Blade指令执行模板应该执行的所有操作。

为此，只需设置环境变量 BLADE_EXPECTS_PHP_TAGS 为 true，如果检测到 <?php 或 <?= 标签，则将抛出异常。

如何工作

指令以两种方式解析

• 像闭包一样提取其参数
• 像PHP块一样解析包装的phpDoc

结果定义告诉要做什么

• 如果没有默认值，参数是必需的，如果未定义则抛出异常
• 如果有默认值，如果未定义则设置此值
• 类型声明 设置所需的类型，如果不匹配则抛出异常（可选）

这将在编译的模板中转换为简单的PHP条件

抛出的异常是

• \Vaites\Laravel\BladeExpects\Exceptions\PhpTagsNotAllowedException
• \Vaites\Laravel\BladeExpects\Exceptions\UndefinedVariableException
• \Vaites\Laravel\BladeExpects\Exceptions\WrongTypeException
• \Vaites\Laravel\BladeExpects\Exceptions\WrongClassException

所有变量都继承自 \Vaites\Laravel\BladeExpects\Exceptions\Exception，该异常继承自 InvalidArgumentException。

要求

• Laravel 5.5 或更高版本
• PHP 7.2 或更高版本

安装

只需使用 composer 进行安装，Laravel 将自动加载它。

composer require vaites/laravel-blade-expects

如果您不想使用包自动发现功能，则需要将以下内容添加到config/app.php文件中的服务提供者配置中。

'providers' => [
    // ...
    \Vaites\Laravel\BladeExpects\BladeExpectsServiceProvider::class,
]

配置

以下环境变量可以被定义：

• BLADE_EXPECTS_ENABLED：布尔值，启用或禁用指令（标签将被移除）
• BLADE_EXPECTS_PHP_TAGS：布尔值，启用或禁用PHP标签的使用

PhpStorm集成

PhpStorm IDE可以识别自定义Blade指令，如果指令在文件 > 设置 > 语言与框架 > PHP > Blade > 指令中设置，可以通过添加以下属性的新指令来实现：

• 名称：expects
• 有参数：勾选
• 前缀：
• 后缀：){}; ?>