README

Robo 参数为 Robo PHP 任务运行器提供任务，以从/向各种格式的文件读取和写入参数。您可以读取参数文件以从中心文件配置任务，或将参数写入配置文件以支持您的部署设置

目前，我们支持 xml、ini、php、yaml 和 json 文件。该库包含一个针对 Symfony 参数文件的专用任务，支持 Symfony XML 和 YAML 格式（目前不支持 Symfony PHP-configuration 格式）。

安装

只需将库作为依赖项添加到您的 composer.json（您通常只在开发中使用它）

{
    "require-dev": {
        "consolidation/robo": "^1.0",
        "nordcode/robo-parameters": "^1.0"
    }
}

或通过控制台

composer require --dev "nordcode/robo-parameters" "^1.0"

如果您需要 YAML 读取器/写入器，您还必须添加 symfony/yaml 组件！

使用方法

安装后，您需要通过导入 trait 将其添加到 RoboFile 中

<?php

use Robo\Tasks;

class RoboFile extends Tasks
{
    use NordCode\RoboParameters\loadTasks;
    
    // ...
}

示例

让我们从一些示例开始。有关不同配置选项的详细信息，请参阅文件末尾的参考。

基本使用

<?php

use Robo\Tasks;

class RoboFile extends Tasks
{
    use NordCode\RoboParameters\loadTasks;

    public function sometask()
    {
        // 1. Load the variables host, port, ... from the environment
        //     variables DB_HOST, DB_PORT, ... and writes them to the file database.xml.
        // 2. If one of the variables could not be found in the environment
        //     the task will fail (this is no default)
        $this
            ->writeParameters('database.xml')
            ->loadFromEnvironment(['host', 'port', 'username', 'password', 'db_name'])
            ->envVariablePrefix('DB')
            ->failOnMissingEnvVariables()
            ->run();
    }
}

从样板文件读取并写入

<?php

use Robo\Tasks;

class RoboFile extends Tasks
{
    use NordCode\RoboParameters\loadTasks;

    public function anothertask()
    {
        // 1. Will load the config.yml.dist file as YAML
        // 2. The parameter mail_host will be read from the environment
        //     variable MAIL_HOST or fail back the mail_host value from the boilerplate file
        // 3. `env` will always be set to "production".
        // 4. The combined data will be written to config.yml
        $this
            ->writeParameters('config.yml')
            ->useBoilerplate('config.yml.dist')
            ->loadFromEnvironment(['mail_host'])
            ->set([
                'env' => 'production'
            ])
            ->run();
    }
}

写入 Symfony parameters.yml

<?php

use Robo\Tasks;

class RoboFile extends Tasks
{
    use NordCode\RoboParameters\loadTasks;
    
    public function configureSymfony()
    {
        // This is how you would configure your Symfony application automatically
        // 1. The app/config/parameters.yml.dist will be used as boilerplate (default)
        // 2. All the specified variables will be loaded from the environment with `SF` as prefix e.g. SF_DATABASE_USER
        //    note that this has NOTHING to do with Symfony's capabilities to load parameters from the env during runtime!
        //    The parameters specified here will be loaded and set while building the project (on deployment).
        //    So you set the environment variables in your CI tool like Jenkins, Travis, GitLab CI, ...
        // 3. Finally the secret will be set to a (stupid) random value and the combined data will be
        //    written to app/config/parameters.xml (note that the boilerplate and final output can have different formats)
        
        // please do not use this for actual secret generation!
        // actually, the secret should be stored in the environment as well
        $stupidSecret = md5(mt_rand());
        
        $this
            ->writeSymfonyParameters('app/config/parameters.xml', null, 'app/config/parameters.yml.dist')
            ->envVariablePrefix('SF')
            ->failOnMissingEnvVariables()
            ->loadFromEnvironment([
                'database_host',
                'database_port',
                'database_user',
                'database_password',
                'mailer_host',
                'mailer_user',
                'mailer_password'
            ])
            ->set('secret', $stupidSecret)
            ->run();
    }
}

与 Laravel (dotenv 文件) 一起使用

<?php

use Robo\Tasks;

class RoboFile extends Tasks
{
    use NordCode\RoboParameters\loadTasks;

    public function configureLaravel()
    {
        // This is a basic example how to configure a Laravel app in your deployment process
        //  Laravel utilizes vlucas/phpdotenv library to load part of your configuration from the .env file
        // 1. Load the distributed configuration from .env.example. You should place common configuration in this file
        // 2. All the specified variables will be loaded from the environment
        // 3. The combined configuration will be written to .env
        $this
            ->writeParameters('.env')
            ->useBoilerplate('.env.example')
            // the keys are case-insensitive so app_env will be read from environment and written to .env as APP_ENV
            ->loadFromEnvironment([
                'app_env',
                'app_url',
                'db_database',
                'db_username',
                'db_password',
                'mail_host',
                'mail_username',
                'mail_password'
            ])
            ->run();
    }
}

Parameters 任务参考

当使用 loadTasks trait 时，可以使用 $this->writeParameters($path, $format = null) 创建新实例。

->set(string $key, mixed $value), ->set(array $values)

将参数设置为固定值。也接受键 => 值对的列表

->loadFromEnvironment(array $parameter_names)

将尝试从环境变量中加载参数名称。
参数名称始终大写，例如，加载参数 foo_bar 将在环境中查找 FOO_BAR

->envVariablePrefix(string $prefix)

要求环境中的所有参数都以前面给定的值作为前缀。
前缀也遵循大写方案，因此使用 sf 作为前缀加载 foo 实际上会搜索 SF_FOO

->failOnMissingEnvVariables()

如果使用 ->loadFromEnvironment() 设置的任何参数无法找到，则任务将失败。

->fileHeader(array $lines), ->fileHeader(string $header)

向输出文件添加注释作为头部。该注释总是输出格式的正确语法。
这可以是一个字符串或行数组

->useBoilerplate(string $path)

从给定的文件中加载所有参数

->overrideExisting()

显式覆盖已存在的参数文件。
如果没有设置，任务将默认失败！

SymfonyParameters 任务参考

专用的 Symfony 任务具有与 Parameters 任务相同的方法。
当使用 loadTask 特性时，将默认创建一个新实例，该实例使用 $this->writeSymfonyParameters()。默认情况下，这使用 YAML 格式，并尝试从 app/config/parameters.yml.dist 加载，并将最终值写入到 app/config/parameters.yml。

FileConfigurable 任务

如果您想通过从中央文件加载一些设置使自己的任务更动态，可以使用 FileConfigurable 特性

<?php
// RoboFile.php

use Robo\Tasks;

class RoboFile extends Tasks
{
    use \NordCode\RoboParameters\FileConfigurable;

    public function __construct()
    {
        // load the configuration for the task from one or multiple files
        // the configurations will be merged into a single array
        // if loading was successful you can use $this->get() in all the following tasks to receive a value
        $this
            ->loadConfiguration('config.dist.yml')
            ->loadConfiguration('config.yml');
    }
    
    public function foo() {
        // basic usage
        $buildDir = $this->get('build_dir', 'some/default/path');
        
        // you can use the dot.notation to access array fields:
        $this->get('environment.dev.build_dir', 'build');
        // .. would be the same as ..
        $this->get('environment')['dev']['build_dir'] ?: 'build';
    }
}