Grumphp Fractor Task Laravel Package

Getting Started

Minimal Steps

1. Install the package as a dev dependency:

   composer require --dev andersundsehr/grumphp-fractor-task
   

2. Enable the task in grumphp.yml:

   grumphp:
       tasks:
           fractor: ~
       extensions:
           - Andersundsehr\GrumPHPFractorTask\ExtensionLoader
   

3. Run GrumPHP to test:

   ./vendor/bin/grumphp run
   

   • Uses default fractor.php config (if present in project root).
   • Triggers on .php files by default.

First Use Case: Enforce declare(strict_types=1)

Add this to grumphp.yml to validate strict typing in Laravel controllers:

tasks:
    fractor:
        triggered_by: ['php']
        ignore_patterns: ['tests/*', 'vendor/*']
        clear_cache: false  # Cache results for faster local runs

Implementation Patterns

Workflow Integration

1. Pre-Commit Hook Add to .git/hooks/pre-commit:

   #!/bin/sh
   ./vendor/bin/grumphp run --triggered-by=php
   

   • Runs Fractor only on staged PHP files.

2. CI Pipeline (GitHub Actions Example)

   - name: Run Fractor
     run: ./vendor/bin/grumphp run --no-cache --strict
   

   • Use --no-cache in CI for consistent results.

Laravel-Specific Configurations

1. Custom Fractor Rules (fractor.php) Override defaults for Laravel:

   return [
       'rules' => [
           'strict_types' => [
               'active' => true,
               'level' => 'error',
               'ignore_files' => ['app/Providers/AppServiceProvider.php'],
           ],
           'class_naming' => [
               'prefix' => 'App\\',
               'suffix' => '',
               'ignore' => ['Migrations', 'Console'],
           ],
       ],
   ];
   

2. Exclude Laravel Artifacts

   tasks:
       fractor:
           ignore_patterns:
               - 'bootstrap/cache/*'
               - 'storage/*'
               - 'vendor/*'
               - 'tests/Feature/*'
   

Task Chaining

Combine with other GrumPHP tasks for a full Laravel workflow:

tasks:
    phpcs_fixer: ~
    fractor: ~
    phpstan: ~
    phpunit: ~

• Order: Run Fractor after phpcs_fixer (fix formatting first) but before phpstan (catch structural issues early).

Gotchas and Tips

Pitfalls

1. Fractor’s TYPO3 Focus

   • Default rules may flag Laravel-specific patterns (e.g., magic methods in AppServiceProvider).
   • Fix: Use ignore_patterns or override rules in fractor.php.

2. Cache Invalidation

   • Cached results may hide new issues if fractor.php changes.
   • Fix: Run with --no-cache locally after config updates:

     ./vendor/bin/grumphp run --no-cache
     

3. Performance in Large Repos

   • Fractor can slow down CI if not optimized.
   • Fix: Limit triggered_by to critical paths:

     triggered_by: ['app/Http/Controllers/', 'app/Models/']
     

Debugging Tips

1. Verbose Output Enable diffs for debugging:

   tasks:
       fractor:
           no_diffs: false
   

2. Isolate Issues Run Fractor on a single file:

   ./vendor/bin/grumphp run --files=app/Http/Controllers/UserController.php
   

3. Check Exit Codes Fractor returns 1 on failures. Use in CI:

   - name: Fractor Check
     run: |
       if ! ./vendor/bin/grumphp run --no-cache; then
         echo "Fractor failed!"
         exit 1
       fi
   

Extension Points

1. Custom Rules Extend Fractor’s ruleset by creating a custom config file (e.g., config/fractor-laravel.php) and reference it:

   tasks:
       fractor:
           config: "config/fractor-laravel.php"
   

2. Dynamic Ignore Patterns Use environment variables for flexible ignores:

   tasks:
       fractor:
           ignore_patterns:
               - "${IGNORE_PATTERN:-tests/*}"
   

3. Parallel Execution Speed up runs with GrumPHP’s parallel flag:

   ./vendor/bin/grumphp run --parallel
   

Laravel-Specific Quirks

• Dynamic Properties: Fractor may flag Laravel’s __get() magic methods. Add to ignore_patterns if needed.
• Service Container: Rules like class_naming may conflict with Laravel’s bind() conventions. Override in fractor.php:

  'class_naming' => [
      'ignore' => ['app/Providers/RepositoryServiceProvider.php'],
  ],