README

介绍

Ellire 简化了您应用程序的部署特定配置。

您为应用程序运行的所有不同“配置文件”提供“宏”配置（例如，dev、test、预发布、prod）以及通过Ellire可以处理所有包含宏的“模板”文件，以生成最终的环境/部署相关的文件。

以下部分将深入介绍这三个主要概念。

模板

模板文件是应用程序代码库中任何具有在 dist_file_extension 宏中定义的扩展名的文件（默认为 template）。这些文件将由Ellire处理，并生成非模板文件（如果您想排除某些目录的处理，则将它们作为以逗号分隔的列表提供，作为项目根目录的相对路径在 template_exclude_paths 宏中）。任何根据其部署的服务器/环境而变化的文件都应制作成模板。

让我们看一个简单的例子。假设您在代码库中的 app/config/config.php 下方有这个文件

<?php
return [
    //...
    'domain' => 'www.example.com',
    'enable_debug' => false,
    'send_emails' => true,
    'mail_from' => 'hello@example.com',
    //...
];

例如，当在本地运行此应用程序时，您将有一个不同的域名，您可能想启用调试模式，也许完全停止发送电子邮件或更改发件人电子邮件。

要使用Ellire实现这一点，您将文件移动到 app/config/config.php.template（或如果您愿意，可以通过更改前面提到的 dist_file_extension 使用不同的扩展名）并注入宏到新的模板文件中

<?php
return [
    //...
    'domain' => '@app_domain@',
    'enable_debug' => @enable_debug@,
    'send_emails' => @send_emails@,
    'mail_from' => '@mail_from_address@',
    //...
];

就这样。模板文件已创建。现在让我们看看宏——它们是什么以及它们来自哪里。

宏

在Ellire中，宏是一段具有名称和值的配置。宏值可以依赖于其他宏值。它们主要在配置文件中定义，但也可以通过命令行参数和环境变量提供。

继续前一个部分的例子，假设您在应用程序中有一个 ellire.json 文件，内容如下...

{
    "globals": {
        "enable_debug": false,
        "port": "",
        "mail_from_address": "hello@example.com"
    },
    "dev": {
        "app_domain": "dev.example.com",
        "enable_debug": true,
        "send_emails": false,
        "port": "8888"
    },
    "prod": {
        "app_domain": "www.example.com",
        "send_emails": true
    }
}

...您的 app/config/config.php.template 将被处理，并且当使用 dev 配置文件时，Ellire将使用以下值生成 app/config/config.php...

<?php
return [
    //...
    'domain' => 'dev.example.com',
    'enable_debug' => true,
    'send_emails' => false,
    'mail_from' => 'hello@example.com',
    //...
];

...并且当使用 prod 配置文件时，以下值

<?php
return [
    //...
    'domain' => 'www.example.com',
    'enable_debug' => false,
    'send_emails' => true,
    'mail_from' => 'hello@example.com',
    //...
];

定义和解析宏值的过程要复杂一些，因此请务必查看宏配置部分。

最后一个例子讨论了配置文件。这个术语在下面的部分中解释。

配置文件

在Ellire中，配置文件基本上是应用程序运行的环境的标识符，例如dev、staging、prod等。

配置文件只是一个任意字符串，因此您可以使用任何您喜欢的或适合您应用程序框架的内容（例如prod、production或live）。唯一例外的是globals，它具有特殊含义 - 它表示适用于所有配置文件的配置。

系统、用户和应用程序配置文件中的宏值按配置文件分组。这意味着您可以在一个文件中预定义和管理所有服务器的配置，当运行Ellire时，它将解析适用于当前服务器的配置文件中的正确宏值。

有关配置文件解析和使用的更多详细信息，请参阅宏配置部分。

宏配置

Ellire根据以下内容解析宏值

系统配置文件（/etc/ellire.json）
用户配置文件（$HOME/.ellire/ellire.json）
本地（应用程序特定的）配置文件，来自您的版本控制系统（例如ellire.json）
特定实例的配置文件（例如.ellire-instance.json）
环境变量
传递给ellire reprocess-templates的手动宏覆盖值

注意：首先根据系统配置文件和用户配置文件的globals部分解析profile、deploy_path和config_extension宏值，然后解析环境变量和宏覆盖。如果您在其他任何地方提供了它们的值，这些值将被忽略。

以下将详细介绍这些内容。

不同的配置文件

系统范围

系统配置文件定义了机器上所有用户的宏值。因此，如果您将在安装Ellire的机器上使用多个用户账户，这个文件尤其有用。

系统配置文件是JSON格式，需要放置在/etc/ellire.json。它可以包含所有配置文件的默认宏值（globals部分），以及应用程序可以运行的所有配置文件的配置。

示例

{
    "globals": {
        "profile": "dev",
        "config_extension": "json",
        "dist_file_extension": "template",
        "generated_files_writable": "false",
        "macro_opening_string": "@",
        "macro_closing_string": "@",
        "template_exclude_paths": "src/, tests/, vendor/",
        "app_domain": "dev.example.com",
        "app_env": "@profile@",
        "url": "https://@app_domain@@port@",
        "enable_debug": false,
        "send_emails": false,
        "port": ""
    },
    "dev": {
        "enable_debug": true
    },
    "prod": {
        "app_domain": "www.example.com",
        "send_emails": true
    }
}

用户特定

用户配置文件仅定义当前用户的宏值。它是JSON格式，需要放置在$HOME/.ellire/ellire.json。它可以包含所有配置文件的默认宏值（globals部分），以及应用程序可以运行的所有配置文件的配置。

示例

{
    "globals": {
        "cache_path": "/home/myuser/custom/cache/path"
    },
    "dev": {
        "port": "8888"
    }
}

应用程序特定

应用程序特定的文件是主要的配置文件 - 它对您写的每个应用程序都是不同的。它应该位于您的项目/应用程序的根目录中，并提交到您的版本控制系统。

该文件的名称始终为ellire，但是您可以通过系统配置文件或用户配置文件中的config_extension宏（可能的选项是json、yml、xml或ini）配置最适合您/您项目的扩展名。它可以包含所有配置文件的默认宏值（globals部分），以及应用程序可以运行的所有配置文件的配置。

示例

{
    "globals": {
        "mail_from": "foo@dev.example.com",
        "ssl_enabled": false,
        "template_exclude_paths": "src/, tests/, app/, node_modules",
    },
    "dev": {
        "db_host": "localhost",
        "db_user": "root",
        "db_pass": "",
    },
    "prod": {
        "mail_from": "user@example.com",
        "ssl_enabled": true,
        "db_host": "db.example.com",
        "db_user": "superapp"
    }
}

实例特定

实例文件允许您为同一台机器上部署的同一应用程序提供不同的宏值（例如，同一台机器上并行运行的同一应用程序的多个测试/开发版本）。此文件永远不应提交到您的版本控制系统。

该文件的名称始终为.ellire-instance，但是您可以通过系统配置文件或用户配置文件中的config_extension宏（可能的选项是json、yml、xml或ini）配置最适合您/您项目的扩展名。它只能包含当前应用程序正在运行配置文件的配置。

示例

{
    "port": "8889",
    "app_debug": false,
    "ssl_enabled": true
}

环境变量

Ellire将检查它所了解的任何宏的值（即您已在配置文件中定义了它们，或在任何模板文件中使用过）。

宏值从具有ELLIRE_前缀的变量中读取。例如

名为foo的宏可以通过ELLIRE_FOO变量设置
名为5%off的宏可以通过ELLIRE_5_OFF变量设置（非字母数字字符将被下划线替换）

宏覆盖

也可以手动覆盖任何宏值。这是通过在ellire reprocess-templates命令中传递-m或--macro来完成的。每个传递的宏必须采用macroName=macroValue格式，例如

ellire reprocess-templates --macro macro1=foo -m macro2=bar

安装

使用composer全局安装Ellire

composer global require ellire/reprocess-templates

创建系统/用户配置文件

一旦安装Ellire，您需要为您的机器/用户账户设置特定的宏配置。为此，可以使用Ellire命令安装默认配置

ellire install-default-config

注意：安装系统配置文件需要具有权限的用户。如果安装失败，Ellire将告诉您并提供手动安装文件的选项。

运行

运行Ellire非常简单

ellire reprocess-templates

这将显示哪些模板文件已更改，哪些保持不变（被跳过）。

要获得更多关于Ellire在运行时正在执行什么操作的详细信息，您可以使用详细模式

ellire reprocess-templates -v

或调试模式

ellire reprocess-templates -vvv

注意：在此模式下，所有解析后的宏（包括您设置的任何敏感数据，如密码、API密钥等）都将显示在STDOUT上。

如前所述以上，您可以在运行ellire时提供单个宏值

ellire reprocess-templates --macro macro1=foo -m macro2=bar

其他命令

除了主要的重新处理模板命令之外，Ellire还提供以下命令

ellire list-macros

列出所有解析和完全处理的宏（模板不会更改）

ellire get-profile

仅显示当前部署使用的配置文件（同样，模板不会更改）。

许可

Ellire采用MIT许可。有关详细信息，请参阅LICENSE文件。

致谢

此项目基于Tim Jackson的杰出（但现在已废弃的）WADF。

ellire / reprocess-templates

维护者

详细信息