README

使用 Laravel 的 Blade 引擎从命令行渲染和保存文本文件。

简介

这是一个 PHP 命令行接口，用于通过命令行渲染 Laravel Blade 模板文本文件。你可以在任何文本文件中嵌入 Laravel Blade 语法，并使用此 CLI 来渲染它。这对于生成 CI/CD 配置文件、配置文件、代码模板等都非常适用。

安装

要安装，请使用全局 composer

composer global require surgiie/laravel-blade-cli

使用

例如，假设你当前目录中有一个名为 person.yml 的文件，内容如下

name: {{ $name }}
relationship: {{ $relationship }}
favorite_food: {{ $favoriteFood }}
@if($includeAddress)
address: 123 example lane
@endif

你可以使用以下命令来渲染此文件

laravel-blade render ./person.yml \
                --name="Bob" \
                --relationship="Uncle" \
                --favorite-food="Pizza" \
                --include-address

这将渲染文件，并将其保存到同一目录中，文件名为 person.rendered.yml，内容如下

name: Bob
relationship: Uncle
favorite_food: Pizza
address: 123 example lane

使用 Docker 运行

如果你没有安装或不想安装 PHP，可以使用提供的 Docker 脚本启动一个容器，然后使用 CLI。

注意 - 此方法的使用需要你挂载需要渲染的目录/文件。容器的当前工作目录是 /app，因此你可以将文件挂载到该目录。

安装 Docker 脚本

cd /tmp

wget https://raw.githubusercontent.com/surgiie/laravel-blade-cli/master/docker

chmod +x ./docker

mv ./docker /usr/local/bin/laravel-blade

然后你可以这样渲染一个文件

# mount the file to the container
docker cp template laravel-blade-cli:/app/template

laravel-blade render /app/template --var="example"

# copy the rendered file back to your host
docker cp laravel-blade-cli:/app/template.rendered ./template.rendered

考虑创建一个 bash 函数来简化将文件挂载和复制到容器的过程。

自定义文件名

默认情况下，所有文件都将保存到渲染文件的同一目录中，文件名为 <filename>.rendered.<extension>，或者如果没有扩展名，则为 <filename>.rendered，以防止覆盖原始文件。要使用自定义文件名或更改目录，请使用 --save-to 选项指定文件路径

laravel-blade render ./person.yml \
            ...
            --save-to="/home/bob/custom-name.yml"

注意：如果 CLI 有权限，它将自动创建必要的父目录，否则将抛出错误。

变量数据

有三种方法可以将变量数据传递给正在渲染的文件，按优先级排序

• 使用具有 --from-yaml 选项的 YAML 文件，并传递文件路径。
• 使用具有 --from-json 选项的 JSON 文件，并传递文件路径。
• 使用具有 --from-env 选项的 env 文件，并传递 .env 文件路径。
• 使用任意命令行选项，如 --example-var=value。

注意：如果需要，可以多次传递 --from-yaml、--from-json 和 --from-env 选项来从多个文件加载。

变量命名约定

你的 env、YAML 和 JSON 文件密钥可以定义为任何命名约定，但实际的变量引用必须是驼峰式命名。这是因为 PHP 不支持 kebab-case 变量，而且这是命令行选项中使用的格式，所以所有变量都将自动转换为驼峰式命名。例如，如果你在文件中传递选项或定义变量名，可以使用以下格式之一： favorite-food、favoriteFood 或 favorite_food，那么该选项的变量应该在该文件中引用为 $favoriteFood。

命令行变量类型

目前支持以下类型的变量

• 字符串/单个值变量：使用单个选项键/值格式，例如 --foo=bar --bar=baz
• 数组值变量：多次传递选项，例如 --names=Steve --names=Ricky --names=Bob
• 真布尔值变量：不带值传递选项，例如 --should-do-thing

注意：由于变量选项是动态的，不支持“否定/假”选项。相反，您可以在文件中使用类似 {{ $shouldDoSomething ?? false }} 的内容，以默认为假，并使用真选项来“否定”值。

强制写入

如果您尝试渲染一个已存在的文件，将会抛出异常。要强制覆盖现有文件，请使用 --force 标志

laravel-blade render ./person.yml \
                --name="Bob" \
                --relationship="Uncle" \
                --favorite-food="Pizza" \
                --include-address \
                --force # force overwrite person.rendered.yml if it already exists.

干燥运行/显示渲染内容

要在不保存的情况下查看渲染文件的 内容，请在渲染单个文件时使用 --dry-run 标志

laravel-blade render example.yaml --some-var=example --dry-run

这将显示 example.yaml 的内容，而不会保存渲染的文件。

处理整个文件目录

您也可以在运行命令时传递目录路径而不是单个文件。当您想一次性渲染多个模板文件时，这可能很有用。

laravel-blade render ./templates --save-dir="/home/bob/templates" --some-data=foo

注意：此命令将提示您确认。要跳过确认，请添加 --force 标志。

注意：在渲染整个目录时，需要使用 --save-dir 选项将所有渲染的文件导出到单独的目录。被处理的目录的目录结构将在保存文件的目录中镜像。在上面的例子中，/home/bob/templates 将具有与 ./templates 相同的目录结构。

缓存/编译目录

当将文件编译成纯 PHP 时，根据 CLI 的使用方式，编译/缓存文件存储在以下可能的位置

• 如果使用独立的/phar 版本的 CLI： /tmp/.laravel-blade-cli
• 如果使用 Docker 构建的 CLI，编译的文件使用默认位置，但这并不重要，因为容器停止后它们将被删除，因此编译的文件不会持久化。
• 如果从仓库克隆并从源代码运行 CLI，编译的文件存储在 storage/framework/compiled 目录中。

清理缓存/编译目录

如果您正在处理大文件或有很多文件需要渲染，缓存/编译文件目录可能会变得非常大，请考虑定期清理。

要清理 24 小时以上的缓存/编译文件目录，请使用 cache:clean 命令

laravel-blade cache:clean

按自定义年龄清理缓存/编译目录

要清理缓存/编译文件目录中超过特定分钟数的文件，请使用 --expires-minutes 选项，例如，要清理超过 60 分钟的文件

laravel-blade cache:clean --expires-minutes=60

强制清理缓存/编译目录

要强制从缓存/编译文件目录中删除所有文件（无论年龄），请使用 --force 标志

laravel-blade cache:clean --force

在渲染前要求文件

如果您需要在渲染文件之前执行自定义代码或逻辑，您可以使用 --require 选项在渲染之前要求一个文件。这对于加载可以在文件中使用的自定义类或函数很有用。为了方便，在要求的文件中有一个特殊的 $__command 变量，它包含命令实例，这可以用于访问命令的选项和参数或如果您需要将文本输出到控制台。您的变量数据也将可用在要求的文件中。您可能还需要在渲染之前修改变量数据，您可以通过在要求的文件中返回要合并到现有变量数据中的数组来完成的变量。

例如，如果您有一个名为 required-file.php 的文件，其内容如下

larave-blade render template.yaml --name="Bob" --require="required-file.php"

<?php

if($name == "Bob") {
    $name = "Uncle Bob";
}

// do more stuff

$__command->info("Did stuff!");

// return mutated variables, will be merged to existing variables
// if no mutation is needed, the return statement is not necessary
return [
    "name" => $name,
];

干燥运行/显示渲染内容

要在不保存的情况下查看渲染文件的 内容，请在渲染单个文件时使用 --dry-run 标志

laravel-blade render example.yaml --some-var=example --dry-run

这将仅显示 example.yaml 的内容，而不会保存渲染的文件。

处理整个文件目录

您也可以在运行命令时传递目录路径而不是单个文件。当您想一次性渲染多个模板文件时，这可能很有用。

laravel-blade render ./templates --save-to="/home/bob/templates" --some-data=foo

注意：当渲染整个目录时，需要使用 --save-to 选项将所有渲染的文件导出到一个单独的目录。正在处理的目录结构将在保存文件的目录中镜像。在上面的例子中，/home/bob/templates 将与 ./templates 具有相同的目录结构。

Blade 组件

匿名渲染组件

如果你在文件中使用匿名 x- blade 组件，你必须指定 --component-path 选项来指定组件所在的位置。

例如，传递 --component-path="/home/components" 将在 /home/components 中查找组件并渲染它们。例如，如果你有一个名为 example.blade.php

的组件在组件目录中，你可以在文件中使用它，如下所示

<x-example :name="$name" />

匿名组件命名空间

如果你希望使用命名空间组件，例如 <x-namespace::component-name />，你可以在 --component-path 选项中使用一个 : 分隔符来指定命名空间和组件名称。

例如，--component-path="namespace:/home/components"。

基于类的组件

由于 CLI 不了解你的类，它不知道如何解析你的组件，为了解决这个问题，你需要通过 --require 文件手动注册你的类。

<?php

// require class or file that loads the classes, such as composer autoload file
require_once "vendor/autoload.php";

use App\View\Components\ExampleComponent;


Blade::component('example', ExampleComponent::class);

然后你可以在文件中使用该组件，如下所示

<x-example :name="$name" />

贡献

以下方式接受贡献

• 问题追踪器
• 拉取请求
• 讨论

许可协议

该项目使用 MIT 许可协议。