Grumphp Config Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev pluswerk/grumphp-config
   

   This auto-generates:

   • grumphp.yml (GrumPHP configuration)
   • rector.php (Rector rules)
   • phpstan.neon (PHPStan configuration)
   • phpstan-baseline.neon (Baseline for existing code)

2. First Use Case: Run GrumPHP on your Laravel project to catch issues early:

   ./vendor/bin/grumphp run
   

   • Fixes will be suggested for:
     • PHPStan errors (type safety, deprecated code).
     • Rector refactoring (e.g., modernizing PHP 7.4+ syntax).
     • PHP-CS-Fixer (coding standards).

3. Where to Look First:

   • grumphp.yml: Override tasks/rules (e.g., exclude vendor/ or add Laravel-specific paths).
   • rector.php: Adjust Rector rules (e.g., skip BooleanInTernaryOperatorRule if needed).
   • .phpstan-baseline.neon: Update baselines after running Rector.

Implementation Patterns

Usage Patterns

1. Laravel-Specific Customization:

   • Exclude Laravel-specific files from GrumPHP:

     # grumphp.yml
     exclude_file_patterns:
       - "vendor/"
       - "bootstrap/cache/*"
       - "storage/framework/*"
     

   • Add Laravel Pint (if using Laravel Pint instead of PHP-CS-Fixer):

     tasks:
       phpcsfixer:
         config: ".php-cs-fixer.dist.php"  # Replace with Laravel Pint config
     

2. Integration with Laravel CI:

   • Add to .github/workflows/laravel.yml:

     - name: Run GrumPHP
       run: ./vendor/bin/grumphp run
     

   • Cache dependencies to speed up CI:

     - uses: actions/cache@v3
       with:
         path: vendor
         key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
     

3. Rector Workflow for Laravel:

   • Run Rector in a pre-commit hook (via GrumPHP) to auto-fix issues:

     tasks:
       rector:
         config: "rector.php"
         dry_run: false  # Auto-fix on commit
     

   • For large Laravel apps, use --parallel:

     ./vendor/bin/rector process src --parallel
     

4. PHPStan for Laravel:

   • Extend phpstan.neon to include Laravel-specific rules:

     includes:
       - vendor/laravel/phpstan/src/Ruleset/LaravelRuleset.neon
     

   • Run PHPStan in CI only (skip locally for speed):

     tasks:
       phpstan:
         configuration: "phpstan.neon"
         triggered_by: ["php"]
         ignore_patterns: ["tests/*"]
     

Workflows

1. Daily Development:

   • Run GrumPHP before committing:

     git add . && ./vendor/bin/grumphp run
     

   • Use grumphp it for interactive mode (fixes issues on the fly).

2. Pre-Release:

   • Run Rector to modernize code:

     ./vendor/bin/rector process src --dry-run
     

   • Update baselines:

     ./vendor/bin/phpstan analyse --generate-baseline
     

3. Onboarding New Devs:

   • Document the grumphp.yml overrides in CONTRIBUTING.md:

     ## Code Quality
     Run `composer require --dev pluswerk/grumphp-config` to set up GrumPHP.
     Override rules in `grumphp.yml` as needed.
     

Gotchas and Tips

Pitfalls

1. Path Issues:

   • Problem: Generated configs use __DIR__ (fixed in v10.2.7+), but older versions may break in subdirectories.
   • Fix: Use getcwd() or update paths manually:

     # grumphp.yml
     paths:
       - "src/"
       - "app/"
     

2. PHPStan Conflicts:

   • Problem: Laravel’s PSR-4 autoloading may cause PHPStan to miss files.
   • Fix: Explicitly include paths:

     # phpstan.neon
     include_files:
       - "app/**/*.php"
       - "src/**/*.php"
     

3. Rector Over-Aggressiveness:

   • Problem: Rector may refactor Laravel-specific code (e.g., config('app.name') to config('app.name')).
   • Fix: Skip problematic rules:

     // rector.php
     return static::configureRules([
         \Rector\Php80\Rector\Class_\ClassPropertyAssignToConstructorRector::class => false,
     ]);
     

4. DDEV Environments:

   • Problem: GrumPHP may fail in DDEV due to path differences.
   • Fix: Use the DDEV_EXEC rule (enabled by default in v10.2.6+):

     # grumphp.yml
     parameters:
       tasks.phpunit.env:
         - "DDEV_EXEC"
     

5. Baseline Management:

   • Problem: Forgetting to update phpstan-baseline.neon after Rector runs.
   • Fix: Add a script to composer.json:

     "scripts": {
       "post-rector": "phpstan analyse --generate-baseline"
     }
     

Debugging

1. GrumPHP Fails Silently:

   • Run with --verbose:

     ./vendor/bin/grumphp run --verbose
     

   • Check logs in ~/.cache/grumphp/.

2. PHPStan Errors:

   • Isolate the issue:

     ./vendor/bin/phpstan analyse --level=max src/Controller/HomeController.php
     

3. Rector Hangs:

   • Use --parallel or limit files:

     ./vendor/bin/rector process src/ --parallel --max-processes=4
     

Extension Points

1. Custom Tasks:

   • Add Laravel-specific tasks (e.g., laravel-pint):

     # grumphp.yml
     tasks:
       laravel-pint:
         command: "php artisan pint"
         on_fail: fail
     

2. Dynamic Configs:

   • Use environment variables in grumphp.yml:

     parameters:
       tasks.phpunit.env:
         - "DB_CONNECTION=${DB_CONNECTION:-mysql}"
     

3. Git Hooks:

   • Integrate with Laravel’s post-commit:

     composer require --dev laravel/git-hooks
     echo "php artisan grumphp" >> .git/hooks/post-commit
     

4. CI-Specific Overrides:

   • Use grumphp.yml.dist for CI-only rules:

     # grumphp.yml (local)
     tasks:
       phpstan: ~
     
     # grumphp.ci.yml (CI-only)
     tasks:
       phpstan:
         level: max
     

Tips

1. Start Strict, Then Relax:

   • Begin with level: max in PHPStan, then adjust baselines incrementally.

2. Leverage grumphp it:

   • Fix issues interactively:

     ./vendor/bin/grumphp it
     

3. Exclude Tests:

   • Skip tests in GrumPHP to speed up runs:

     # grumphp.yml
     exclude_file_patterns:
       - "tests/*"
     

4. Monitor Performance:

   • Cache GrumPHP results in CI:

     # .github/workflows/laravel.yml
     - uses: actions/cache@v3
       with:
         path: ~/.cache/grumphp
         key: ${{ runner.os }}-grumphp-${{ hashFiles('**/composer.lock') }}
     

5. Document Overrides:

   • Add a CODE_QUALITY.md file to explain custom rules for new devs.