Weave Code
Grumphp Laravel Package
phpro/grumphp
GrumPHP is a Composer plugin that automatically registers Git hooks and runs configurable code-quality tasks (linters, static analysis) on committed code. If a check fails, the commit is blocked, helping teams enforce best practices consistently with minimal configuration.
GrumPHP is a Composer plugin that enforces code quality automatically by registering Git hooks in your repository. Whenever someone commits changes, it runs a configurable set of tests against the committed code and blocks the commit if anything fails—so standards are enforced consistently instead of debated in code review.
- Zero-friction setup: hooks attach themselves to your project on install
- Batteries included: a rich set of common tasks works with minimal configuration
- Team-wide consistency: teaches contributors your agreed best practices
- Flexible install: use the dependency-free shim, full package, or Phive
Requires php, composer, and git on the command line.
Frequently asked questions about Grumphp
- Is GrumPHP compatible with Laravel?
- Yes. GrumPHP v2.x is compatible with Laravel 8+ and works with PHP 7.4+, with PHP 8.x recommended. It fits Laravel projects because it installs through Composer and supports tasks such as PHPUnit, Pest, PHPStan, PSR-12, and Laravel Pint.
- How do I install GrumPHP in a Laravel project?
- Install it as a dev dependency with composer require --dev phpro/grumphp, or use phpro/grumphp-shim for a phar without dependencies. Ensure php, composer, and git are discoverable on the command line. After installation, GrumPHP attaches itself to your project's Git hooks and starts checking commits.
- How do I configure GrumPHP tasks for Laravel?
- Define your checks in grumphp.yml using built-in tasks such as PHPUnit, Pest, PHPStan, PSR-12, and Laravel Pint. For custom Laravel-specific behavior, you can extend GrumPHP through its event-driven task system and Laravel's service container. Keep the task list focused so commits stay fast while enforcing the standards your team cares about.
- What PHP and Laravel versions does GrumPHP v2 support?
- The GrumPHP v2.x line requires PHP 7.4+, with PHP 8.x recommended, and Laravel 8+ is fully supported. The older PHP 5.6+ requirement applies to the legacy v1.x branch. Laravel 5.5-era applications cannot use the v2.x line.
- Does GrumPHP v2.25.0 fix a security vulnerability?
- Yes. GrumPHP v2.25.0 closes an argument-injection vector where crafted filenames beginning with a hyphen could be interpreted as external-tool options. It normalizes repository paths by prefixing them with ./ and makes the git_blacklist task match filenames literally. Upgrade repos to phpro/grumphp:^2.25 and avoid running versions at or below v2.24.0 against untrusted branch content.
- Can GrumPHP conflict with existing Git hooks?
- It can. GrumPHP installs Git hooks, so existing hooks may need manual resolution even though backups are created. For automated installs, use --no-scripts during composer install to avoid unexpected hook attachment, then resolve hooks deliberately.
- How do I run or test GrumPHP in CI without Git hooks?
- Run grumphp run as a standalone pipeline step to bypass Git hooks and test the same quality checks in CI. This is useful when you want reproducible validation on every push or pull request. You can also run it locally before enabling hooks for the team.
- How can I improve GrumPHP performance on large Laravel codebases?
- Enable parallel task execution and tune max_workers, for example between 8 and 32, to reduce overhead on large codebases. Keep only high-value checks in the pre-commit hook and move slower checks to CI when needed. Parallelism is the main mitigation noted for performance risk.
- Is GrumPHP suitable for monorepos?
- Monorepos are supported but require careful configuration. Pay attention to hooks_dir and git_hook_variables so hooks attach to the right repository area. Validate the setup on a sample branch before rolling it out across the monorepo.
- Is upgrading from GrumPHP v2.21.0 to v2.25.0 safe?
- Yes. The delta from v2.21.0 to v2.25.0 has no architectural change and no public API, config schema, or task contract changes. No config migration is expected, and the main reason to upgrade is the v2.25.0 security hardening. Standardize on phpro/grumphp:^2.25 and confirm composer/composer is not pinned below 2.10.3.
Weaver
How can I help you explore Laravel packages today?