README

配置文件生成器（confgen）——通过处理Twig模板和任意输入数据结构，快速生成结构化（配置）文件的一种简单方法。

输入数据
模板
元变量
配置
二进制使用
库使用
- 工厂
  - Twig_Environment
  - createConfgen()
- Confgen
  - processTemplate()
  - processDefinition()
安装
测试
许可证

输入数据

本项目全部关于转换你的输入数据结构。

因此，它不对你处理什么类型的输入数据做任何假设，只要它可以表示为简单的JSON结构。本项目专注于JSON输入数据，原因如下：

任意数据结构
- 可以包含几乎所有数据结构
- 简单、合理、严格的数据类型
- 扁平或深层嵌套的结构
- 默认无模式 - 但提供使用模式的选择
易于消费（易于阅读）
- 对人类和机器都一样
- 易于推理
- 很好地映射到模板文件中使用的点分隔符
易于生产（易于编写）
- 简单转换为许多其他常见格式，如YAML、XML、CSV、INI等
- 非常容易在PHP和其他许多语言中编写
广泛应用

你的输入数据可能已经在一个JSON文件中。如果不是，那么使用以下示例代码中的某些代码非常容易进行转换或使用：

// $data = loadFromYaml('input.yml');
// $data = parseFromIni('input.ini');
$data = fetchFromDatabase();
file_put_contents('data.json', json_encode($data));

你的输入数据文件的结构完全由你自己决定。这个库允许你使用任何任意输入数据结构。以下示例假设以下（完全随机的）输入数据结构

{
    "timeout": 120,
    "interfaces": [
        {
            "name": "eth0",
            "address": "192.168.1.1"
        }
    ]
}

模板

每个（配置）模板文件本质上是一个带有占位符的纯文本（输出）配置文件。

模板文件使用Twig模板语言，因此可以利用其变量替换和高级模板控制逻辑。

在最简单的形式中，任意模板可能看起来像这样

timeout = {{ data.timeout }}
{% for interface in data.interfaces %}
auto {{ interface.name }}
    address {{ interface.address }}
{% endfor %}

输入变量可以在data键下访问。

你可以通过调用confgen来生成输出（配置）文件，如下所示

$ confgen -t template.twig -d data.json

在这个例子中，它将结果文件写入无扩展名的模板文件名（即template）。

使用上述示例模板和输入数据，生成的输出（配置）文件可能看起来像这样

timeout = 120
auto eth0
    address 192.168.1.1

元变量

可选地，你可以在模板文件内容之前加上元数据，形式为YAML前端。这种语法很简单，对于模板处理程序和静态网站生成器（如Jekyll）来说很常见。

这意味着如果你想包括元数据变量，那么每个部分都以三个短横线分隔符（---）开始，所以一个完整的文件可能看起来像这样

---
target: /etc/network/interfaces
chmod: 644
reload: /etc/init.d/networking reload
---
timeout = {{ data.timeout }}
{% for interface in data.interfaces %}
auto {{ interface.name }}
    address {{ interface.address }}
{% endfor %}

已记录变量

target - 要写入结果文件的目标路径。可以是绝对路径或相对路径，该路径将相对于confgen被调用的目录解析（即不是相对于此模板文件）。
chmod - 目标文件的文件权限（十进制）
reload 命令在写入目标文件后执行
description 人类可读的描述

您还可以传递任意自定义元数据。有关更多详细信息，请参阅元数据模式。

元变量将在 Twig 模板中的 meta 键下可访问。如果没有 元数据 变量，则此键默认为空数组。

你可以通过调用confgen来生成输出（配置）文件，如下所示

$ confgen -t template.twig -d data.json

如果模板元数据包含一个 target 键，它将结果文件写入此位置。

在上面的示例中，这意味着以下操作将执行

将输出（配置）文件写入 /etc/network/interfaces
设置文件权限为 0644
执行重新加载脚本 /etc/init.d/network restart

有时跳过由元变量 reload 定义的脚本/命令的执行很有用。为此，您可以使用可选参数 --no-scripts 如此

$ confgen --no-scripts -t template.twig -d data.json

配置

您可以选择解析/处理单个模板文件，或者使用允许您一次处理多个文件的配置定义。

在最简单的形式中，JSON 配置结构看起来像这样

{
    "templates": "example/*.twig"
}

已记录变量

templates 可以是绝对路径或相对路径，该路径将与此定义相关（即不一定是 $PWD）

有关更多详细信息，请参阅配置模式。

您可以通过如下方式调用 confgen 来生成输出（配置）文件

$ confgen [--no-scripts] -c confgen.json -d data.json

这与通过单个模板文件调用相似。

二进制使用

一旦安装，您可以使用此工具作为 bin（二进制）可执行文件。

上面给出了一些用法示例。

如果您想查看用法帮助，只需通过调用它的帮助命令如下

$ confgen

如果您通过 $ composer require 安装，则可能需要按如下方式调用它

$ ./vendor/bin/confgen

库使用

有关 bin 使用的详细信息，通常更容易开始。

如果您想将其集成到另一个工具中，您还可以使用此项目作为库。如果您想使用自定义 twig 扩展、函数或过滤器，这也适用。

工厂

Factory 类是一个辅助类，可用于轻松创建新的 Confgen 实例。

$factory = new Factory();

Twig_Environment

内部，Factory 将创建一个 Twig_Environment 实例，该实例将用于处理模板文件。

如果您想使用以下任何内容，您可能需要显式传递一个实例

自定义 twig 扩展
自定义 twig 函数
自定义 twig 过滤器

$twig = new Twig_Environment();
$twig->addFilter(new Twig_SimpleFilter('backwards', function ($value) {
    return strrev($value);
});

$factory = new Factory($twig);

createConfgen()

createConfgen() 方法用于创建新的 Confgen 实例。通常，不需要调用此方法超过一次。

$confgen = $factory->createConfgen();

Confgen

Confgen 类负责处理模板（这里发生魔法的地方）。

processTemplate

processTemplate($templateFile, $dataFile) 方法可以用来从给定的模板文件生成输出（配置）文件。

$confgen->processTemplate('template.twig', 'data.json');

processTemplate($templateFile, $dataFile) 方法在 reload 命令失败时抛出 RuntimeException。有关 reload 的更多详细信息，请参阅元变量部分。

请参阅上面的模板部分，以获取有关输入数据的更多详细信息。

processDefinition

processDefinition($definitionFile, $dataFile)方法可以用于从给定的配置文件生成任意数量的输出（配置）文件。

$confgen->processDefinition('confgen.json', 'data.json');

当reload命令失败时，processDefinition($definitionFile, $dataFile)方法会抛出RuntimeException。请参阅元变量部分以获取有关reload的更多详细信息。

请参阅上面的配置部分以获取更多详细信息。

安装

您可以直接将预编译好的版本作为Phar文件下载到任何目录。只需从我们的发布页面下载最新的confgen.phar文件。

测试

要运行测试套件，您首先需要克隆此存储库，然后通过Composer安装所有依赖项。

$ composer install

要运行测试套件，请转到项目根目录并运行

$ php vendor/bin/phpunit

许可证

MIT

clue / confgen

维护者

详细信息