Weave Code
Grumphp Laravel Package
phpro/grumphp
GrumPHP is a Composer plugin that installs Git hooks to run quality checks (tests, linters, code style) on staged changes before you commit. If tasks fail, the commit is blocked—helping teams enforce standards and improve code quality automatically.
A PHP code-quality tool
Frequently asked questions about Grumphp
- How do I integrate GrumPHP with Laravel’s Pest/PHPUnit tests to block failing tests on commit?
- Add the `phpunit` task to your `grumphp.yml` with the `--testsuite` flag targeting your Pest or PHPUnit suite. For Laravel, use `php artisan test --testsuite=unit` or similar. Ensure `stop_on_failure: true` to block commits with failing tests. GrumPHP runs tests in parallel by default, reducing feedback time.
- Will GrumPHP work with Laravel Sail/Docker environments, or do I need to configure paths?
- GrumPHP works with Docker/Sail, but you may need to adjust paths in `grumphp.yml` using `git_hook_variables` or `parameters`. For example, set `parameters.task.phpunit.config_file: tests/unit` to point to Laravel’s test directory. Use `ignore_unstaged_changes: true` to avoid issues with Docker volumes.
- Can GrumPHP enforce Laravel-specific rules like Blade template validation or migration syntax checks?
- Yes, create custom tasks using GrumPHP’s `Task` class or leverage existing tools like `laravel-blade-checker` (via `exec` task). For migrations, add a custom `ExecTask` running `php artisan migrate:status --pretend` to catch syntax errors. Document these rules in your team’s `grumphp.yml` for consistency.
- How do I exclude Laravel’s `vendor/` or `storage/` directories from GrumPHP checks?
- Use the `paths` configuration in `grumphp.yml` to exclude directories: `paths: [src/, tests/]`. For dynamic exclusions (e.g., `storage/logs/`), add a `CustomTask` with `ignore_unstaged_changes: true` and regex-based filtering. Avoid excluding critical paths like `app/` to maintain code quality.
- Does GrumPHP support Laravel 10+ and PHP 8.1+ features like attributes or strict typing?
- GrumPHP fully supports PHP 8.1+ and Laravel 10+. Use PHPStan’s `level: 9` (strict) in your config to enforce Laravel’s typed properties and return types. For attributes, configure PHPStan’s `parameters.rules.attributes` to validate custom attributes used in Laravel’s DI container or middleware.
- How can I test GrumPHP locally before enabling Git hooks for the team?
- Run `grumphp run` manually to test tasks without triggering hooks. Use `--no-hooks` during installation to bypass automatic hook setup. For Laravel, simulate a commit with `git add . && grumphp run --dry-run` to preview blocked changes. Document the output in your team’s onboarding guide.
- What’s the best way to handle environment-specific GrumPHP rules (e.g., local vs. production)?
- Use `parameters.task.<task>.config_file` to point to environment-specific configs (e.g., `grumphp.local.yml`). For Laravel, leverage `.env`-based logic in custom tasks (e.g., skip Blade checks in `APP_ENV=testing`). Avoid hardcoding paths; use `getcwd()` or Laravel’s `base_path()` in custom scripts.
- Can GrumPHP replace my Laravel CI checks (e.g., GitHub Actions), or should they run separately?
- GrumPHP should mirror *critical* CI checks (e.g., tests, linting) locally to catch issues early. Use `grumphp run --strict` in CI as a final gate. For Laravel, duplicate only non-environment-specific checks (e.g., PHPStan) in CI, while keeping environment-dependent tasks (e.g., database tests) in CI-only pipelines.
- How do I configure GrumPHP to work with Laravel Pint for code formatting?
- Add the `exec` task to `grumphp.yml` with `command: vendor/bin/pint --test`. For Laravel, ensure Pint’s config (`pint.json`) aligns with your team’s standards. Run Pint via GrumPHP pre-commit to enforce consistent formatting, reducing CI feedback for style issues.
- What’s the performance impact of GrumPHP on large Laravel codebases, and how do I optimize it?
- GrumPHP’s parallel execution (`parallel.max_workers: 4–8`) mitigates overhead, but large codebases may benefit from selective task inclusion. Disable verbose output (`verbose: false`) and cache results with `parameters.task.phpstan.cache_directory`. For Laravel, prioritize critical tasks (e.g., tests, critical linting) and defer others to CI.
Weaver
How can I help you explore Laravel packages today?