GrumPHP

Sick and tired of complaining about your co-workers' code? GrumPHP will do it for you! This composer plugin will register some git hooks in your package repository. When somebody commits changes, GrumPHP will run some tests on the committed code. If the tests fail, you won't be able to commit your changes. This handy tool will make your co-workers care about their code.

GrumPHP has a set of common tasks built-in. You will be able to use GrumPHP with a minimum of configuration.

We don't want to bore you with all the details, so quick: install it yourself and unleash the power of GrumPHP!

Installation

This package is composer plugin and should be installed to your project's dev dependency using composer:

composer require --dev phpro/grumphp:~0.1

When the package is installed, GrumPHP will attach itself to the git hooks of your project. You will see following message in the composer logs:

Watch out! GrumPHP is sniffing your commits!

To make GrumPHP even more awesome, it will suggest installing some extra packages:

• squizlabs/php_codesniffer : ~2.3
• phpspec/phpspec : ~2.1
• roave/security-advisors : dev-master@dev

GrumPHP will never push you into using a specific task. You can choose the tasks that fit your needs, and activate or deactivate any task in no time!

Installation with an exotic project structure:

When your application has a project structure that is not covered by the default configuration settings, you will have to create a grumphp.yml file at the same location as composer.json before installing the package.

It is possible to place your configuration file at another location or change the configuration after installation. The only downfall is that you will have to initialize the git hook manually:

php ./vendor/bin git:init --config=path/to/grumphp.yml

Configuration

Sample grumphp.yml:

parameters:
    bin_dir: "./vendor/bin"
    git_dir: "."
    tasks:
        phpcs:
            standard: "PSR2"
        phpspec: ~

Parameters

bin_dir

Default: ./bin/vendor

This parameter will tell GrumPHP where it can locate external commands like phpcs and phpspec. It defaults to the default composer bin directory.

git_dir

Default: .

This parameter will tell GrumPHP in which folder it can find the .git folder. This parameter is used to create the git hooks at the correct location. It defaults to the working directory.

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:

parameters:
    tasks:
        phpcs: ~
        phpspec: ~

Every task has it's own default configuration. It is possible to overwrite the parameters per task.

Phpcs

The Phpcs task will sniff your code for bad coding standards. It lives under the phpcs namespace and has following configurable parameters:

standard

Default: PSR2

This parameter will describe which standard is being used to validate your code for bad coding standards.

show_warnings

Default: true

Triggers an error when there are warnings.

tab_width

Default: null

By default, the standard will specify the optimal tab-width of the code. If you want to overwrite this option, you can use this configuration option.

ignore_patterns

Default: []

This is a list of patterns that will be ignored by phpcs. With this option you can skip files like tests. Leave this option blank to run phpcs for every php file.

sniffs

Default: []

This is a list of sniffs that need to be executed. Leave this option blank to run all configured sniffs for the selected standard.

Phpspec

The Phpspec task will spec your code with Phpspec. It lives under the phpspec namespace and has following configurable parameters:

config_file

Default: null

If your phpspec.yml file is located at an exotic location, you can specify your custom config file location with this option.

stop_on_failure

Default: false

When this option is enabled, phpspec will stop at the first error. This means that it will not run your full test suite when an error occurs.

Custom tasks

It is very easy to configure your own project specific task. You just have to create a class that implements the GrumPHP\Task\TaskInterface. Next register it to the service manager and add your task configuration:

parameters:
    tasks:
        myConfigKey:
            config1: config-value
            
services:
    task.myCustomTask:
        class: My\Custom\Task
        arguments:
          - @config
          - "@=parameter('tasks')['myConfigKey'] ? parameter('tasks')['myConfigKey'] : []"
        tags:
          - {name: grumphp.task, config: myConfigKey}

Note: You do NOT have to add the main and task configuration. This example just shows you how to do it. You're welcome!

You just registered your custom task in no time! Pretty cool right?!

Roadmap

Following tasks are still on the roadmap:

• phpunit
• behat
• composer.json and composer.lock need to be committed at the same time
• ...

Execution

GrumPHP will be triggered with GIT hooks. However, you can execute the trigger at the command line:

php ./vendor/bin git:pre-commit

Compatibility

This package has been tested with following git clients:

• CLI unix
• Phpstorm GIT
• Atlassian SourceTree

Todo:

• CLI Windows
• other popular git clients