DOCSEARCHbyAlgolia
Submit Docs

GrumPHP Documentation

repository·v2.x·Indexed 26 days ago

https://github.com/phpro/grumphp

GrumPHP is a Composer plugin that automates code quality enforcement by registering Git hooks. It runs validation tasks such as tests, linters, and fixers during the commit process to prevent failing code from being committed. It supports PHP 5.6+ and various Git clients, offering a CLI for manual task execution and a YAML-based configuration system for defining tasks, extensions, and project conventions.

Tokens
42.1K
Snippets
162
Records
282
Agent score
87%

What's inside GrumPHP

  1. Understand Mago Linter behavior in GrumPHP

    v2.x

    The Mago Linter task has specific behaviors depending on the execution context:

    • Default Mode: The task always runs in --fix --dry-run mode. It previews automatic fixes without modifying files and fails if issues are found.
    • Git Pre-commit: When running in a git pre-commit context, only staged files are linted (--staged).
    • Run Context: When running via the run command, all files are linted.
    • Auto-fixing: If the task fails, GrumPHP will offer to re-run the task with --fix applied based on your configured fix-mode.

  2. Understand Mago Guard behavior and performance

    v2.x

    Mago Guard runs the mago guard command and fails if an architectural violation is found.

    Important considerations:

    • Contexts: It runs in both git pre-commit and run contexts. It does not have a --staged mode; architectural rules are evaluated against the entire project.
    • Performance: Because every pre-commit run scans the full project, evaluate if mago_guard is fast enough for your codebase before enabling it as a pre-commit task.
    • No Auto-fix: Mago Guard only reports violations; it does not provide an auto-fix mechanism.

  3. Mago Analyzer behavior and execution context

    v2.x

    Mago Analyzer runs mago analyze to provide diagnostic output. Its behavior changes based on the execution context:

    • git pre-commit context: Only staged files are analyzed using the --staged flag.
    • run context: All files are analyzed.

    If the task fails, GrumPHP provides an option to re-run the analysis with the --fix flag applied, governed by your fix-mode configuration.

  7. Replace the abandoned SensioLabs Security Checker

    v2.x

    The SensioLabs Security Checker API is abandoned and no longer supported. To perform security checks within GrumPHP, you must use one of the following replacement tasks instead:

    • securitychecker_composeraudit
    • securitychecker_enlightn
    • securitychecker_local
    • securitychecker_roave
    • securitychecker_symfony

  10. Add Composer global bin to your system PATH

    v2.x
    After installing GrumPHP globally, ensure that the Composer global vendor bin directory is included in your system $PATH variable so the grumphp command can be executed from any terminal session. Typically, this directory is located at ~/.composer/vendor/bin.

  11. Create a GrumPHP extension

    v2.x

    You can group custom tasks or event listeners into an extension to centralize logic and reuse it across projects. To create an extension, implement the GrumPHP\Extension\ExtensionInterface and use the imports() method to yield paths to configuration files.

    Supported loaders for configuration files are YAML, XML, INI, GLOB, and DIR. Note that PHP and CLOSURE loaders are not supported to ensure compatibility with the grumphp-shim PHAR distribution.

    An extension can append multiple configuration files to the Symfony dependency injection container used by GrumPHP.

    <?php
namespace My\Project;

use GrumPHP\Extension\ExtensionInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class MyAwesomeGrumPHPExtension implements ExtensionInterface
{
    public function imports(): iterable
    {
        $configDir = dirname(__DIR__).'/config';
    
        yield $configDir.'/my-extension.yaml';
        yield $configDir.'/my-extension.xml';
        yield $configDir.'/my-extension.ini';
        yield $configDir.'/my-extension/*';
    }
}