Weave Code
Grumphp Shim Laravel Package
phpro/grumphp-shim
Provides a bundled GrumPHP PHAR so you can run GrumPHP without installing all its dependencies. Install via Composer and run vendor/bin/grumphp.phar run. Links to the main phpro/grumphp repo for options and release notes.
This repository provides easy way to install GrumPHP without the risk of conflicting dependencies.
Frequently asked questions about Grumphp Shim
- Can I use this package to enforce Laravel Pint rules in pre-commit hooks without bloating my project’s dependencies?
- Yes, this package lets you run Laravel Pint (or any GrumPHP task) via a self-contained PHAR, avoiding conflicts with your Laravel project’s dependencies. Configure Pint rules in `.grumphp.yml` and trigger it via `vendor/bin/grumphp.phar run` in your pre-commit hook. The PHAR isolates Pint’s requirements from your project’s `composer.json`.
- How do I integrate this with Laravel’s Pest testing framework for pre-commit test execution?
- Add Pest to your `.grumphp.yml` under `tasks` with the `pest` task, then run `vendor/bin/grumphp.phar run` in your pre-commit hook. The PHAR bundles Pest’s dependencies, so no additional Composer installs are needed. Example: `tasks: pest: ~`. Ensure your Laravel project’s Pest version is compatible with the GrumPHP PHAR’s bundled version.
- Will this work in a Laravel monorepo where multiple projects have conflicting PHPUnit versions?
- Yes, but you’ll need to explicitly pin PHPUnit (or other task) versions in `.grumphp.yml` to avoid conflicts. The PHAR isolates dependencies per project, so each can use its own PHPUnit version. Test locally first to confirm compatibility, as GrumPHP’s PHAR may bundle a different version than your Laravel project.
- How do I configure GrumPHP to run only specific tasks (e.g., PHPStan) in pre-commit and others (e.g., security checks) in CI?
- Use the `--tasks` flag in your pre-commit hook (e.g., `vendor/bin/grumphp.phar run --tasks=phpstan`) and let CI run the full suite. Alternatively, define separate configurations in `.grumphp.yml` (e.g., `grumphp.ci.yml`) and reference them conditionally. Enable caching (`--cache`) for faster local runs.
- Does this package support Laravel’s Git workflows, like running checks after `git merge` but not on every commit?
- Yes, you can integrate it with Laravel’s post-merge hooks by adding a custom script in `.git/hooks/post-merge` that calls `vendor/bin/grumphp.phar run`. For branch-specific checks, use environment variables or conditional logic in your hook to trigger GrumPHP only when needed, reducing overhead.
- What Laravel versions and PHP versions does this package support? Will it break if my project uses PHP 8.1 but GrumPHP’s PHAR requires 8.2?
- The package supports the same PHP versions as the underlying GrumPHP PHAR (check the [GrumPHP repo](https://github.com/phpro/grumphp) for details). If your Laravel project uses PHP 8.1 but the PHAR requires 8.2, you’ll need to either downgrade GrumPHP or run it in a separate environment (e.g., Docker). Test compatibility early, as PHP version mismatches can cause silent failures.
- How do I debug a ‘PHAR failed’ error when running GrumPHP in a Laravel project?
- Run GrumPHP with verbose output and redirect logs to a file: `vendor/bin/grumphp.phar run --verbose > grumphp.log`. Check the log for specific errors (e.g., missing PHP extensions, task configuration issues). Common culprits include unmet task dependencies (e.g., `ext-gmp` for PHPUnit) or conflicts with Laravel’s `composer.json` constraints. Document troubleshooting steps for your team.
- Can I use this package alongside Laravel’s built-in testing tools (e.g., PHPUnit) without duplicate checks?
- Yes, but avoid redundancy by consolidating checks in `.grumphp.yml`. For example, if you’re already running PHPUnit in CI, use GrumPHP only for pre-commit linting or static analysis. Disable overlapping tasks in GrumPHP to prevent duplicate work. Example: Exclude PHPUnit from GrumPHP if your Laravel project runs tests via `php artisan test`.
- What are the performance implications of running GrumPHP in pre-commit for large Laravel codebases?
- Pre-commit runs can slow down if you include heavy tasks like PHPStan or security checks. Mitigate this by enabling caching (`--cache`), excluding slow tasks from pre-commit, or running them only on specific branches. For large teams, consider running lightweight checks (e.g., PSR-12 linting) in pre-commit and deferring heavier tasks to CI.
- Are there alternatives to this package for running GrumPHP in Laravel without dependency conflicts?
- Alternatives include installing GrumPHP globally via `composer global require phpro/grumphp` or using a Docker container to isolate dependencies. However, this package offers a cleaner solution for Laravel projects by embedding the PHAR in `vendor/bin`, avoiding global installs or complex setup. If you need more control, consider the official GrumPHP package (`phpro/grumphp`) but be prepared to manage dependency conflicts manually.
Weaver
How can I help you explore Laravel packages today?