Grumphp Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev phpro/grumphp
   

   This auto-configures Git hooks. Verify with:

   composer show grumphp
   

2. First Run:

   composer grumphp
   

   Or trigger via Git pre-commit hook by staging changes and running:

   git commit -m "Test commit"
   

3. Default Tasks: GrumPHP includes built-in tasks (e.g., phpunit, psalm, phpcs). Check grumphp.yml for active tasks.

First Use Case: Enforcing PSR-12

Add PSR-12 validation to grumphp.yml:

grumphp:
  tasks:
    phpcs:
      standard: "PSR12"
      triggered_by: ["php"]
      ignore_patterns: ["vendor/"]

Now, commits violating PSR-12 will fail.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline: Use grumphp run in CI (e.g., GitHub Actions) to block merges:

   # .github/workflows/grumphp.yml
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install --no-dev
         - run: composer grumphp
   

2. Parallel Execution: Enable parallel tasks in grumphp.yml:

   grumphp:
     parallel:
       enabled: true
       max_workers: 8
   

   Faster feedback for large codebases.

3. Task Grouping: Group related tasks (e.g., testing + linting) using testsuites:

   grumphp:
     testsuites:
       test:
         tasks: [phpunit, phpmd]
       lint:
         tasks: [phpcs, phpcbf]
   

   Run with:

   composer grumphp --testsuite=test
   

Laravel-Specific Patterns

1. Artisan Task Integration: Run GrumPHP via Artisan (add to composer.json scripts):

   {
     "scripts": {
       "grumphp": "grumphp run"
     }
   }
   

   Trigger with:

   php artisan grumphp
   

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

   // app/Console/Commands/GrumLaravelMigrations.php
   use GrumPHP\Task\TaskInterface;
   use GrumPHP\Runner\TaskResult;
   
   class GrumLaravelMigrations implements TaskInterface {
       public function getConfig(): array { return []; }
       public function run(): TaskResult {
           $result = new TaskResult();
           if (!Artisan::call('migrate:status')) {
               $result->setOk(false);
               $result->addViolation('Migrations not up-to-date!');
           }
           return $result;
       }
   }
   

   Register in grumphp.yml:

   grumphp:
     tasks:
       app.tasks.laravel-migrations:
         class: App\Console\Commands\GrumLaravelMigrations
   

3. Environment-Specific Hooks: Use git_hook_variables for Laravel Forge/Envoyer:

   grumphp:
     git_hook_variables:
       EXEC_GRUMPHP_COMMAND: "php /home/forge/app.php"
   

Gotchas and Tips

Pitfalls

1. Hook Overwrites:

   • GrumPHP overwrites existing Git hooks. Backup hooks first:

     cp .git/hooks/pre-commit .git/hooks/pre-commit.bak
     

   • Disable auto-install with:

     composer install --no-scripts
     

2. Parallel Execution Quirks:

   • Tasks with side effects (e.g., file I/O) may fail in parallel mode. Use parallel.enabled: false for such tasks.

3. Environment Variables:

   • Strings in environment.variables must be quoted (even for numbers):

     environment:
       variables:
         APP_ENV: "testing"
         DEBUG: "1"
     

4. Task Dependencies:

   • Some tasks (e.g., phpunit) require specific setup. Ensure dependencies are installed:

     composer require --dev phpro/grumphp phpunit/phpunit
     

Debugging

1. Dry Run: Test without committing:

   composer grumphp --no-git-hook
   

2. Verbose Output: Enable debug mode:

   composer grumphp --verbose
   

3. Task Isolation: Run a single task:

   composer grumphp --task=phpcs
   

4. Git Hook Debugging:

   • Check hook execution with:

     GIT_TRACE=1 git commit -m "Test"
     

   • Temporarily disable hooks to test:

     git config core.hooksPath .git/hooks/
     

Tips

1. Custom Config File: Use a .grumphp.yml in project root for team-specific rules:

   grumphp:
     tasks:
       phpcs:
         ignore_patterns: ["tests/"]
   

2. Fixer Mode: Auto-fix issues with fixer.enabled: true and fix_by_default: true:

   grumphp:
     fixer:
       enabled: true
       fix_by_default: true
   

   Run with:

   composer grumphp --fix
   

3. Event Listeners: Extend GrumPHP with events (e.g., Slack notifications on failure):

   // app/Listeners/GrumSlackListener.php
   use GrumPHP\Event\RunnerFailedEvent;
   
   class GrumSlackListener {
       public function onRunnerFailed(RunnerFailedEvent $event) {
           $client = new SlackClient();
           $client->sendMessage("GrumPHP failed: " . $event->getMessage());
       }
   }
   

   Register in grumphp.yml:

   services:
     App\Listeners\GrumSlackListener:
       tags:
         - { name: grumphp.event_listener, event: grumphp.runner.failed }
   

4. CI-Specific Config: Override settings for CI (e.g., disable parallelism):

   # .grumphp.ci.yml
   grumphp:
     parallel:
       enabled: false
   

   Load in CI:

   composer grumphp --config=.grumphp.ci.yml
   

5. Task Prioritization: Control task order with priority (lower = earlier):

   grumphp:
     tasks:
       phpcs:
         priority: 100
       phpunit:
         priority: 200
   

6. Local vs. Remote: Use hooks_preset: vagrant for remote environments:

   grumphp:
     hooks_preset: vagrant
     git_hook_variables:
       VAGRANT_PROJECT_DIR: "/var/www/project"