grumphp

Register the Git hooks

$ grumphp git:init

$ grumphp git:pre-commit

$ grumphp run

grumphp <command> [options]

Common commands include:

grumphp init
grumphp run [--skip-success-text] [--test-suite=<suite>]
grumphp git:deactivate

--help
    Displays help for the specified command or lists available commands.

--version
    Displays the application version.

--config=<path>
    Specifies a custom path to the grumphp.yml or grumphp.yaml configuration file.

--test-suite=<suite>
    Only runs tasks associated with a specific test suite as defined in the configuration.

--tasks=<tasks>
    Only runs a specific list of tasks (comma-separated names) instead of all configured tasks.

--skip-success-text
    Suppresses the 'GrumPHP is sniffing your code!' success message during execution.

--no-interaction
    Do not ask any interactive questions during command execution. Useful for automation scripts.

--env=<environment>
    Sets the environment for which to run tasks (e.g., dev, prod).

GrumPHP is a powerful, flexible tool designed to automate code quality checks within a Git workflow. By leveraging Git's pre-commit, pre-merge, and pre-push hooks, GrumPHP allows developers to define a series of tasks—such as linting, static analysis, code style checks, or unit tests—that must pass before a commit or push is finalized. This proactive approach helps maintain high code standards, catches errors early, and ensures consistency across a development team. It's highly configurable, supporting a wide array of PHP tools like PHPStan, PHPLint, PHP_CodeSniffer (PHPCS), PHPUnit, and more, making it an essential part of a robust Continuous Integration/Continuous Delivery (CI/CD) pipeline for PHP projects. Its primary goal is to prevent faulty or non-compliant code from entering the shared codebase, thereby improving overall project quality and developer efficiency.

Requires a PHP environment with Composer installed and a Git repository. Can introduce a slight delay to commit or push operations, depending on the number and complexity of configured tasks. Configuration can become intricate for complex projects or highly customized task definitions. Primarily designed for PHP projects and Git-based version control systems.

GrumPHP's behavior is entirely controlled by a configuration file, typically named grumphp.yml or grumphp.yaml, located in the project's root directory. This YAML file defines which tasks to run, their specific configurations, and which test suites they belong to.

GrumPHP is installed as a development dependency via Composer. After installation (composer require --dev phpro/grumphp), it is activated in the Git repository using the command grumphp init, which sets up the necessary Git hooks.

In urgent situations, GrumPHP checks can be temporarily bypassed during a commit by adding --no-verify to the git commit command (e.g., git commit -m "Emergency fix" --no-verify) or by including [skip grumphp] or [GrumPHP skip] in the commit message if configured in grumphp.yml.

GrumPHP was initially developed by the team at Phpro and first released around 2014-2015. It emerged as a solution to streamline code quality enforcement in PHP projects, addressing the need for automated checks directly within the Git workflow. Its design focuses on flexibility and extensibility, allowing developers to easily integrate various code analysis and testing tools. Over the years, it has gained significant traction within the PHP community, becoming a widely adopted tool for pre-commit hook management due to its robust features, active development, and strong community support.

git(1), composer(1), php(1), phpcs(1), phpstan(1), phpunit(1)