Skip to content

Latest commit

 

History

History
283 lines (239 loc) · 8.57 KB

tasks.md

File metadata and controls

283 lines (239 loc) · 8.57 KB
Raw

Tasks

It is easy to configure and activate tasks in GrumPHP. Tasks live under their own namespace in the parameters part. To activate a task, it is sufficient to add an empty task configuration:

# grumphp.yml
grumphp:
    tasks:
        ant: ~
        atoum: ~
        behat: ~
        brunch: ~
        clover_coverage: ~
        codeception: ~
        composer: ~
        composer_normalize: ~
        composer_require_checker: ~
        composer_script: ~
        deptrac: ~
        doctrine_orm: ~
        ecs: ~
        eslint: ~
        file_size: ~
        gherkin: ~
        git_blacklist: ~
        git_branch_name: ~
        git_commit_message: ~
        grunt: ~
        gulp: ~
        infection: ~
        jsonlint: ~
        kahlan: ~
        make: ~
        npm_script: ~
        paratest: ~
        pest: ~
        phan: ~
        phing: ~
        php7cc: ~
        phpcpd: ~
        phpcs: ~
        phpcsfixer: ~
        phplint: ~
        phpmd: ~
        phpmnd: ~
        phpparser: ~
        phpspec: ~
        phpstan: ~
        phpunit: ~
        phpunitbridge: ~
        phpversion: ~
        progpilot: ~
        psalm: ~
        rector: ~
        robo: ~
        securitychecker_composeraudit: ~
        securitychecker_enlightn: ~
        securitychecker_local: ~
        securitychecker_roave: ~
        securitychecker_symfony: ~
        shell: ~
        stylelint: ~
        tester: ~
        twigcs: ~
        twigcsfixer: ~
        xmllint: ~
        yamllint: ~

Every task has its own default configuration. It is possible to overwrite the parameters per task.

Tasks

Metadata

Every task has a pre-defined metadata key on which application specific options can be configured. For example:

# grumphp.yml
grumphp:
    tasks:
        anytask:
            metadata:
                blocking: true
                enabled: true
                label: null
                priority: 0
                task: null

blocking

Default: true

This option can be used to make a failing task non-blocking. By default, all tasks will be marked as blocking. When a task is non-blocking, the errors will be displayed but the tests will pass.

enabled

Default: true

This option can be used to disable task execution. By default all tasks will be enabled. This makes it possible to conditionally run a task by setting parameters or changing the value through an extension.

label

Default: null

This option can be used to display a label instead of the task name whilst running GrumPHP. By default, the task name will be displayed.

priority

Default: 0

This option can be used to specify the order in which the tasks will be executed. The higher the priority, the sooner the task will be executed. All tasks with the same priority will run in parallel if parallel execution is enabled.

task

Default: null

This option can be used to specify which task you want to run. This way you can configure the same task twice by using an alias with different options. (For more information see below.)

Creating a custom task

Creating a custom task is a matter of implementing the provided GrumPHP\Task\TaskInterface. When your task is written, you have to register it to the service manager and add your task configuration to grumphp.yml:

<?php

interface TaskInterface
{
    public static function getConfigurableOptions(): ConfigOptionsResolver;
    public function canRunInContext(ContextInterface $context): bool;
    public function run(ContextInterface $context): TaskResultInterface;
    public function getConfig(): TaskConfigInterface;
    public function withConfig(TaskConfigInterface $config): TaskInterface;
}
  • getConfigurableOptions: This method has to return all configurable options for the task.
  • canRunInContext: Tells GrumPHP if it can run in pre-commit, commit-msg or run context.
  • run: Executes the task and returns a result
  • getConfig: Provides the resolved configuration for the task or an empty config for newly instantiated tasks.
  • withConfig: Is used by GrumPHP to inject configuration during runtime. It should be immutable by default.
# grumphp.yml
grumphp:
    tasks:
        myConfigKey:
            config1: config-value

services:
    My\Custom\Task:
        arguments:
            - '@some.required.dependency'
        tags:
            - {name: grumphp.task, task: defaultTaskName, priority: 0}

You now registered your custom task! Pretty cool right?!

❗Note: Be careful with adding dependencies to your task. When GrumPHP runs in parallel mode, the task and all of its dependencies get serialized in order to run in a separate process. This could lead to a delay when e.g. serializing a depenency container or lead to errors on unserializable objects. More info

❗Note: You can use Symfony's options-resolver to help configure the options for your task. However, if you want your task to work together with the grumphp-shim (phar) distribution, you will have to make sure to use ConfigOptionsResolver::fromClosure() This is because the Symfony's options-resolver gets scoped in the phar. Example:

public static function getConfigurableOptions(): ConfigOptionsResolver
{
    $resolver = new OptionsResolver();

    // ..... your config

    return ConfigOptionsResolver::fromClosure(
        static fn (array $options): array => $resolver->resolve($options)
    );
}

Testing your custom task.

We provided some base phpunit classes which you can use to test your tasks. For a more detailed view on how to use these classes, you can scroll through our own unit tests section.

  • GrumPHP\Test\Task\AbstractTaskTestCase : For testing basic tasks that don't trigger an external command.
  • GrumPHP\Test\Task\AbstractExternalTaskTestCase : For testing tasks that trigger external commands.

Run the same task twice with different configuration

In some cases you might want to run the same task but with different configuration. Good news: This is perfectly possible! You can use any name you want for the task, as long as you configure an existing task in the metadata section. Configuration of the additional task will look like this:

# grumphp.yml
grumphp:
    tasks:
        phpcsfixer:
            allow_risky: true
            path_mode: intersection
        phpcsfixer_typo3:
            allow_risky: true
            config: .typo3.php-cs-fixer.php
            path_mode: intersection
            metadata:
                task: phpcsfixer