Getting Started

Minimal Setup

Install the package in your Laravel project:

composer require --dev phpro/grumphp-shim

Initialize GrumPHP by creating a .grumphp.yml config file in your project root. Use the GrumPHP docs for reference.

# Example minimal config
parameters:
    tasks:
        phpcs:
            standard: PSR12
        phpunit: ~

Run GrumPHP via the shim:

vendor/bin/grumphp.phar run

Or add it to your composer.json scripts for easier access:

"scripts": {
    "grumphp": "vendor/bin/grumphp.phar run"
}

Then execute with:

composer grumphp

First Use Case: Pre-Commit Hooks

To enforce checks before commits, add a Git hook or use a Composer script:

# Add to your .git/hooks/pre-commit (or use a tool like husky)
#!/bin/sh
composer grumphp

Now, GrumPHP will run automatically on git commit.

Implementation Patterns

Workflow Integration

Laravel-Specific Tasks Leverage Laravel’s ecosystem by configuring GrumPHP tasks in .grumphp.yml:
```
tasks:
    laravel-pint: ~
    pest: ~
    phpstan:
        level: 5
        configuration: phpstan.neon
```
This ensures code formatting, testing, and static analysis align with Laravel’s standards.

CI/CD Pipeline Use the shim in CI to fail fast on quality issues:

# GitHub Actions example
jobs:
    grumphp:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-php@v3
              with:
                  php-version: '8.2'
            - run: composer install --dev
            - run: vendor/bin/grumphp.phar run

Custom Tasks Extend GrumPHP with custom tasks (e.g., security checks):

tasks:
    custom:
        command: ./vendor/bin/security-checker security:check
        ignore_failure: false

Common Patterns

Cache Results Speed up local runs by caching results:

vendor/bin/grumphp.phar run --cache

Add this to your composer.json scripts for convenience:

"scripts": {
    "grumphp": "vendor/bin/grumphp.phar run --cache"
}

Parallel Execution Run tasks in parallel to reduce execution time:

parameters:
    parallel:
        enabled: true
        tasks:
            - phpcs
            - phpunit

Environment-Specific Configs Use multiple config files for different environments (e.g., grumphp.ci.yml):
```
vendor/bin/grumphp.phar run --config=grumphp.ci.yml
```

Laravel-Specific Tips

Pest Integration Configure Pest tasks in GrumPHP to run alongside PHPUnit:
```
tasks:
    pest: ~
    phpunit: ~
```
Ensure your pest.php config is compatible with GrumPHP’s execution environment.

Artisan Commands Use GrumPHP to validate Artisan commands or migrations:

tasks:
    custom:
        command: php artisan migrate:status
        ignore_failure: false

Gotchas and Tips

Pitfalls

PHAR Execution Issues
- Symptom: vendor/bin/grumphp.phar fails with "PHAR error" or permission issues.
- Fix: Ensure the PHAR has executable permissions:
```
chmod +x vendor/bin/grumphp.phar
```
- Debug: Run with --verbose to diagnose:
```
vendor/bin/grumphp.phar run --verbose
```

Dependency Conflicts

Symptom: GrumPHP tasks (e.g., phpunit) fail due to version mismatches with Laravel’s dependencies.

Fix: Explicitly define task versions in .grumphp.yml:

tasks:
    phpunit:
        config_file: phpunit.xml
        group: []
        test_class: []
        bootstrap: tests/bootstrap.php
        configuration: []
        colors: true
        process_isolation: false
        stop_on_failure: false
        test_suffix: Test
        test_loader_class: PHPUnit\TextUI\TestRunner
        test_loader_options: []
        group_by_test_class: false

Tip: Use the same PHPUnit/Pest versions as your Laravel project.

Git Hook Conflicts
- Symptom: GrumPHP fails silently in Git hooks due to environment differences (e.g., missing .env).
- Fix: Mock the environment in hooks or use a wrapper script:
```
#!/bin/sh
cp .env.testing .env
composer grumphp
```
Performance Overhead
- Symptom: GrumPHP runs slowly in CI or local environments.
- Fix:
  - Cache results locally (--cache).
  - Run in parallel (see Implementation Patterns).
  - Exclude heavy tasks (e.g., phpstan) from pre-commit hooks.

Debugging Tips

Verbose Output Use --verbose to diagnose issues:
```
vendor/bin/grumphp.phar run --verbose
```
Dry Runs Test configurations without executing tasks:
```
vendor/bin/grumphp.phar run --dry-run
```
Task-Specific Debugging Run individual tasks to isolate failures:
```
vendor/bin/grumphp.phar phpcs
vendor/bin/grumphp.phar phpunit
```

Configuration Quirks

Path Handling
- GrumPHP may fail if paths in .grumphp.yml are relative. Use absolute paths or ~ for project root:
```
tasks:
    phpcs:
        standard: PSR12
        paths:
            - ~
```
PHP Version Mismatches
- The shim defaults to the PHP version used to install it. Ensure your Laravel project’s PHP version matches:
```
php -v  # Check your project's PHP version
```
Task Ordering
- Tasks run in the order defined in .grumphp.yml. Reorder for dependencies (e.g., phpcs before phpstan).

Extension Points

Custom Tasks Extend GrumPHP with custom tasks. Example:

tasks:
    custom:
        command: ./vendor/bin/your-custom-script.sh
        ignore_failure: false

Pre/Post Hooks Use GrumPHP’s hooks to run scripts before/after tasks:

parameters:
    hooks:
        before:
            - ./scripts/pre-check.sh
        after:
            - ./scripts/post-check.sh

Dynamic Configs Load configs dynamically based on environment variables:

parameters:
    config:
        - .grumphp.yml
        - .grumphp.${ENV}.yml

Laravel-Specific Gotchas

Environment Variables GrumPHP may not load .env automatically. Use a wrapper script or set variables explicitly:
```
#!/bin/sh
export APP_ENV=testing
composer grumphp
```
Artisan Commands Avoid running Artisan commands directly in GrumPHP if they rely on Laravel’s service provider bootstrapping. Use php artisan with a full Laravel bootstrap:
```
tasks:
     custom:
         command: php artisan your:command
         ignore_failure: false
```

Grumphp Shim Laravel Package