Grumphp Laravel Package

## Getting Started

### Minimal Setup for Laravel
1. **Installation**
   ```bash
   composer require --dev phpro/grumphp

GrumPHP auto-configures git hooks. Verify with:

composer grumphp:run

2. Basic Configuration Create grumphp.yml in your Laravel project root:

   grumphp:
     tasks:
       phpcs:
         standard: PSR12
       phpmd:
         rulesets: ["cleancode", "codesize", "controversial", "design", "naming", "unusedcode"]
       phpunit: ~
   

3. First Use Case Run GrumPHP manually to test:

   composer grumphp:run
   

   Or trigger via git commit (hooks enabled by default).

Implementation Patterns

Laravel-Specific Workflows

1. Task Integration with Laravel Features

   • Artisan Commands: Extend GrumPHP to run Laravel-specific tasks (e.g., artisan:test):

     tasks:
       artisan:
         commands: ["test"]
         args: ["--env=testing"]
     

   • Environment-Specific Configs: Use Laravel’s .env in GrumPHP:

     environment:
       variables:
         APP_ENV: "{{ env('APP_ENV') }}"
     

2. Parallel Task Execution Leverage Laravel’s queue system for heavy tasks (e.g., phpstan):

   parallel:
     enabled: true
     max_workers: 4  # Match Laravel queue workers
   

3. Task Dependencies Chain tasks like Laravel’s service providers:

   tasks:
     phpcs:
       triggered_by: ["phpmd"]
   

4. Custom Tasks Create a Laravel-specific task (e.g., laravel:routes):

   // app/GrumPHP/Task/LaravelRoutesTask.php
   namespace App\GrumPHP\Task;
   use GrumPHP\Task\Task;
   class LaravelRoutesTask extends Task {
       public function run() {
           $routes = app()->routes->getRoutes();
           // Custom logic...
       }
   }
   

   Register in grumphp.yml:

   tasks:
     app:laravel:routes: ~
   

5. CI/CD Integration Use GrumPHP in Laravel Forge/Laravel Envoyer:

   # .github/workflows/ci.yml
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - run: composer grumphp:run --strict
   

Gotchas and Tips

Laravel-Specific Pitfalls

1. Git Hook Conflicts

   • Issue: GrumPHP overwrites hooks. Laravel Forge/Envoyer may conflict.
   • Fix: Use composer grumphp:git:deinit before deploying, then reinitialize post-deploy:

     composer grumphp:git:init
     

2. Environment Variables

   • Issue: .env vars not passed to tasks.
   • Fix: Explicitly load Laravel’s env in grumphp.yml:

     environment:
       files: [".env"]
     

3. Task Caching

   • Tip: Cache slow tasks (e.g., phpstan) using Laravel’s cache:

     tasks:
       phpstan:
         cache: true
         cache_file: ~/.cache/grumphp/phpstan.laravel.cache
     

4. Debugging Fixer Issues

   • Gotcha: fix_by_default: true may auto-fix Laravel’s APP_KEY or DB configs.
   • Fix: Exclude sensitive files:

     fixer:
       enabled: true
       fix_by_default: false
       exclude_files: ["config/app.php", "config/database.php"]
     

5. Parallel Execution Quirks

   • Issue: Laravel’s queue workers may interfere with GrumPHP’s parallel tasks.
   • Fix: Limit workers or disable parallelism:

     parallel:
       enabled: false
     

6. Task Event Listeners

   • Tip: Hook into Laravel’s events (e.g., ModelSaved) to trigger GrumPHP:

     // app/Providers/AppServiceProvider.php
     public function boot() {
         event(new \GrumPHP\Runner\Event\RunnerEvent());
     }
     

7. Strict Mode for CI

   • Best Practice: Use --strict in CI to fail builds:

     composer grumphp:run --strict
     

8. Laravel Mix/Valet Conflicts

   • Issue: Valet’s php path conflicts with GrumPHP’s EXEC_GRUMPHP_COMMAND.
   • Fix: Specify full path:

     git_hook_variables:
       EXEC_GRUMPHP_COMMAND: "/usr/local/bin/php"
     

9. Task Prioritization

   • Tip: Use priority to run critical tasks first (e.g., phpunit before phpcs):

     tasks:
       phpunit:
         priority: 100
     

10. Laravel Debugbar Integration

    • Tip: Log GrumPHP results to Debugbar:

      // app/Providers/AppServiceProvider.php
      use GrumPHP\Runner\Event\RunnerEvent;
      public function boot() {
          event(new RunnerEvent());
          \Debugbar::info('GrumPHP Results', $this->grumphpResults);
      }
      

11. Excluding Vendor Files

    • Gotcha: GrumPHP scans vendor/ by default.
    • Fix: Exclude in config:

      tasks:
        phpcs:
          exclude: ["vendor/**"]
      

12. Custom Artisan Commands

    • Tip: Create a grumphp:custom command in Laravel:

      php artisan make:command GrumPHPRun
      

      Extend GrumPHP\Console\Command\RunCommand.

13. Windows-Specific Issues

    • Gotcha: Git hooks may fail on Windows.
    • Fix: Use WSL or configure EXEC_GRUMPHP_COMMAND:

      git_hook_variables:
        EXEC_GRUMPHP_COMMAND: "wsl php"
      

14. Laravel Sail/Docker

    • Tip: Run GrumPHP inside Sail containers:

      git_hook_variables:
        EXEC_GRUMPHP_COMMAND: "sail grumphp:run"
      

15. Task Result Storage

    • Tip: Store GrumPHP results in Laravel’s database:

      // After RunnerEvent::complete
      \App\Models\GrumPHPResult::create([
          'output' => $event->getOutput(),
          'status' => $event->isSuccessful() ? 'passed' : 'failed',
      ]);
      

---