Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time


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
        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_enlightn: ~
        securitychecker_local: ~
        securitychecker_roave: ~
        securitychecker_symfony: ~
        shell: ~
        stylelint: ~
        tester: ~
        twigcs: ~
        xmllint: ~
        yamllint: ~

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



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

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


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.


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.


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.


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.


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:


interface TaskInterface
    public static function getConfigurableOptions(): OptionsResolver;
    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
            config1: config-value

            - '@some.required.dependency'
            - {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

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
            allow_risky: true
            path_mode: intersection
            allow_risky: true
            config: .typo3.php-cs-fixer.php
            path_mode: intersection
                task: phpcsfixer