README

基于 Robo 的PHP任务运行器，注重可扩展性。

快速参考

• 安装
• 配置
• 内置命令
• 以YAML配置的形式暴露自定义命令
• 以PHP类的形式暴露自定义命令

安装

使用 Composer 安装

composer require openeuropa/task-runner

安装后运行 ./vendor/bin/run 以获取可用命令列表。

使用Docker Compose

或者，您可以使用提供的配置通过 Docker 和 Docker Compose 构建一个开发站点。

Docker 提供了必要的服务和工具，以在本地主机配置不受影响的情况下运行测试。

要求

• Docker
• Docker Compose

配置

默认情况下，Docker Compose 读取两个文件，一个 docker-compose.yml 和一个可选的 docker-compose.override.yml 文件。按照惯例，docker-compose.yml 包含您的基本配置，并默认提供。重写文件，正如其名称所暗示的，可以包含对现有服务或全新服务的配置重写。如果服务在两个文件中都定义，Docker Compose 会合并配置。

有关Docker Compose扩展机制的更多信息，请参阅官方Docker Compose文档。

使用方法

要开始，请运行

docker-compose up

建议不要以守护进程模式运行 docker-compose，这样您可以在完成工作后快速将其关闭（CTRL+C）。但是，如果您想以守护进程模式运行它，您必须添加标志 -d

docker-compose up -d

然后

docker-compose exec web composer install

运行测试

要运行 grumphp 检查

docker-compose exec web ./vendor/bin/grumphp run

要运行 phpunit 测试

docker-compose exec web ./vendor/bin/phpunit

配置

Task Runner 提供了一个有用的命令（config），允许检查和调试配置。要了解如何使用它，请运行

./vendor/bin/run config --help

Task Runner 命令可以通过两种方式自定义

1. 在运行命令时设置参数和选项。
2. 在配置文件中提供默认值。任务运行器将按指定顺序读取以下文件。较晚文件中提供的选项将覆盖较早的选项
   • Task Runner 提供的默认值。此文件位于 Task Runner 仓库中的 config/runner.yml。
   • runner.yml.dist - 项目特定的默认设置。此文件应放置在依赖于任务运行器的项目的根目录中。使用此文件声明默认选项，这些选项在正常情况下应与您的应用程序一起工作。此文件应提交到项目中。
   • 第三方可能实现配置提供程序以修改配置。配置提供程序是一个实现了ConfigProviderInterface接口的类。此类应放置在相对命名空间TaskRunner\ConfigProviders下。例如，当Some\Namespace指向src/目录时，则配置提供程序类应放置在src/TaskRunner/ConfigProviders目录下，并将命名空间设置为Some\Namespace\TaskRunner\ConfigProviders。类的名称应以ConfigProvider后缀结尾。使用::provide()方法来修改配置对象。可以在类的文档块中定义@priority注释标签，以确定配置提供程序的运行顺序。如果省略，则假定@priority 0。此机制还允许在流程中插入自定义YAML配置文件，请参见以下示例

     namespace Some\Namespace\TaskRunner\ConfigProviders;
     
     use OpenEuropa\TaskRunner\Contract\ConfigProviderInterface;
     use OpenEuropa\TaskRunner\Traits\ConfigFromFilesTrait;
     use Robo\Config\Config;
     
     /**
      * @priority 100
      */
     class AddCustomFileConfigProvider implements ConfigProviderInterface
     {
         use ConfigFromFilesTrait;
         public static function provide(Config $config): void
         {
             // Load the configuration from custom.yml and custom2.yml and
             // apply it to the configuration object. This will override config
             // from runner.yml.dist (which has priority 1500) but get
             // overridden by the config from runner.yml (priority -1000).
             static::importFromFiles($config, [
                 'custom.yml',
                 'custom2.yml',
             ]);
         }
     }
     

   • runner.yml - 项目特定的用户覆盖。此文件也位于依赖于任务运行器的项目的根目录中。此文件可以用来覆盖与用户的本地环境特定的选项。将此文件添加到.gitignore中是良好实践，以防止意外将runner.yml提交到项目存储库。
   • 存储在环境变量中的用户提供的全局覆盖。这些可以用来定义适用于使用任务运行器的所有项目的特定于环境的配置，例如数据库凭证和GitHub访问令牌。以下位置将被检查，并使用找到的第一个位置
     • $OPENEUROPA_TASKRUNNER_CONFIG
     • $XDG_CONFIG_HOME/openeuropa/taskrunner/runner.yml
     • $HOME/.config/openeuropa/taskrunner/runner.yml

• 安装

可以在默认的runner.yml中找到默认值列表及其简要说明。

内置命令

任务运行器包含以下内置命令

运行./vendor/bin/run help [command-name]以获取有关每个命令功能的更多信息。

将“动态”命令作为YAML配置公开

任务运行器允许您通过在runner.yml.dist/runner.yml中的commands:属性下列出tasks来公开新命令。

例如，以下YAML部分将公开两个动态命令：drupal:site-setup和setup:behat

commands:
  drupal:site-setup:
    - { task: "chmod", file: "${drupal.root}/sites", permissions: 0774, recursive: true }
    - { task: "symlink", from: "../../custom/modules", to: "${drupal.root}/modules/custom" }
    - { task: "symlink", from: "../../custom/themes", to: "${drupal.root}/themes/custom" }
    - { task: "run", command: "drupal:drush-setup" }
    - { task: "run", command: "drupal:settings-setup" }
    - { task: "run", command: "setup:behat" }
    - "./vendor/bin/drush --root=$(pwd)/${drupal.root} cr"
  setup:behat:
    - { task: "process", source: "behat.yml.dist", destination: "behat.yml" }

命令可以相互引用，这使得以相对容易的方式实现复杂场景成为可能。

目前支持以下任务（括号内为可选参数的默认值）

作为纯文本字符串提供的任务将在当前工作目录中按原样执行。

将自定义命令作为PHP类公开

可以通过在项目中的PSR-4命名空间内创建Task Runner命令类来提供更复杂的命令。

例如，假设你在composer.json中有以下PSR-4命名空间

{
    "autoload": {
        "psr-4": {
            "My\\Project\\": "./src/"
        }
    }
}

然后你可以通过在./src/TaskRunner/Commands下创建一个或多个类来公开额外的命令，如下例所示

<?php

namespace My\Project\TaskRunner\Commands;

use OpenEuropa\TaskRunner\Commands\AbstractCommands;

/**
 * Class MyCustomCommands
 *
 * @package My\Project\TaskRunner\Commands
 */
class MyCustomCommands extends AbstractCommands
{
    /**
     * @command my-project:command-one
     */
    public function commandOne() { }

    /**
     * @command my-project:command-two
     */
    public function commandTwo() { }
}

完成上述操作后，请运行composer dump-autoload以刷新您的本地自动加载器。

现在，您可以通过Task Runner的主可执行文件访问您的新命令

$ ./vendor/bin/run
OpenEuropa Task Runner

Available commands:
 ...
 my-project
  my-project:command-four
  my-project:command-one

注意：将您的命令类放在./src/TaskRunner/Commands下是强制性的，否则Task Runner在启动时不会注册它们。

尽管不是强制性的，但建议您的命令类扩展OpenEuropa\TaskRunner\Commands\AbstractCommands。

有关如何公开自定义命令的更多详细信息，请参阅主要的Robo文档。

贡献

请阅读完整文档以了解我们的行为准则以及向我们提交拉取请求的过程。

版本控制

我们使用SemVer进行版本控制。有关可用版本，请参阅此存储库的标签。