README

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

快速参考

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

安装

使用Composer安装它

composer require openeuropa/task-runner

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

使用Docker Compose

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

Docker提供必要的服务和工具来运行测试，无论您的本地主机配置如何。

要求

配置

默认情况下，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

配置

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

./vendor/bin/run config --help

任务运行器命令可以通过两种方式自定义

在运行命令时设置参数和选项。
在配置文件中提供默认值。任务运行器将按指定顺序读取以下文件。较后文件中提供的选项将覆盖较早的选项
- 任务运行器提供的默认值。此文件位于任务运行器仓库中的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 - 项目特定用户覆盖。此文件位于依赖Task Runner的项目根目录中。此文件可以用于使用特定于用户本地环境的值覆盖选项。建议将此文件添加到.gitignore中，以防止runner.yml意外提交到项目仓库。
- 用户提供的全局覆盖存储在环境变量中。这些可以用来定义适用于使用Task Runner的所有项目的环境特定配置，例如数据库凭据和Github访问令牌。以下位置将进行检查，并使用第一个找到的位置
  - $OPENEUROPA_TASKRUNNER_CONFIG
  - $XDG_CONFIG_HOME/openeuropa/taskrunner/runner.yml
  - $HOME/.config/openeuropa/taskrunner/runner.yml

安装

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

内置命令

Task Runner包含以下内置命令

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

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

Task Runner允许您通过在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）进行版本管理。有关可用版本，请参阅此存储库的标签。

openeuropa / task-runner

维护者

详细信息