Grumphp Laravel Package

Getting Started

Start by installing GrumPHP via Composer in your project: composer require --dev phpro/grumphp. Run ./vendor/bin/grumphp init to generate the default grumphp.yml configuration file. This creates hooks in .git/hooks/ to run checks on every commit. Your first use case is likely enforcing code style: configure PSR-12 compliance by adding phpcs or php-cs-fixer tasks in the config, then commit a file with style violations to see it blocked and auto-fixed.

Implementation Patterns

• Task Composition: Chain multiple tasks (e.g., phpcs, phpstan, pest, composer validate) in grumphp.yml under tasks:—GrumPHP runs them in order and halts on first failure.
• Per-Task Configuration: Customize each task’s settings (e.g., phpcs: {standard: PSR12, ignore_patterns: [var/*]}) to avoid noise from generated files.
• Environment-aware Hooks: Use grumphp.sh or grumphp.bat wrappers to pass context (e.g., --skip-tests during hotfix commits) via arguments or env vars.
• CI Integration: Add ./vendor/bin/grumphp run --no-progress --verbose to CI pipelines; configure grumphp-ci.yml to exclude interactive prompts and format output for CI logs.
• IDE Support: Hook into PhpStorm’s “Before Commit” actions or VS Code’s Git hooks extension to run GrumPHP interactively—view inline errors via --show-formatters for human-readable output.

Gotchas and Tips

• Git Hook Conflicts: GrumPHP replaces .git/hooks/pre-commit. If using other tools (e.g., Husky via Git hooks), integrate via .githooks/ or use grumphp run --hook to bypass automatic hook management.
• False Positives from Parallel Runs: Tasks may fail intermittently in parallel mode (parallel: true). If reproducible failures occur, disable parallelism or add stop_on_failure: false to isolate flaky tasks.
• Performance Bottlenecks: Large repos slow commits due to file diffs scanning everything. Mitigate with ignore_patterns and use grumphp run --only-changed (via custom task wrapper) to limit scope.
• Config Reloading: GrumPHP caches config. After editing grumphp.yml, run ./vendor/bin/grumphp configure:remove-cache to force reload.
• Extensibility: Override default tasks or add custom ones by creating GrumPHP\Task\ConfigurableTaskInterface implementations and register them in grumphp.yml under extensions: or via a custom grumphp.php script.