Rector Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev driftingly/rector-laravel
   

2. Basic Configuration (auto-detects Laravel version from composer.json):

   // rector.php
   use Rector\Config\RectorConfig;
   use RectorLaravel\Set\LaravelSetProvider;
   
   return RectorConfig::configure()
       ->withSetProviders(LaravelSetProvider::class)
       ->withComposerBased(laravel: true);
   

3. First Run:

   vendor/bin/rector process src
   

First Use Case

Upgrade from Laravel 10 → 11:

• Run Rector with auto-detected rules:

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

• Review changes, then apply:

  vendor/bin/rector process src
  

Implementation Patterns

Version-Specific Upgrades

• Auto-Detection: Use withComposerBased(laravel: true) to auto-select rules based on composer.json.
• Manual Targeting: For specific upgrades (e.g., Laravel 12 → 13):

  ->withSets([LaravelLevelSetList::UP_TO_LARAVEL_130])
  

Common Workflows

1. Collection Improvements:

   ->withSets([LaravelSetList::LARAVEL_COLLECTION])
   

   Converts collect($array)->toArray() → $array (if redundant).

2. Facade to DI:

   ->withSets([LaravelSetList::LARAVEL_STATIC_TO_INJECTION])
   

   Replaces Cache::get() → inject Cache into constructor.

3. Testing Upgrades:

   ->withSets([LaravelSetList::LARAVEL_TESTING])
   

   Converts assertSee() → assertStringContains().

Integration Tips

• CI/CD: Add to php-cs-fixer workflows for pre-commit checks:

  # .github/workflows/rector.yml
  - name: Run Rector
    run: vendor/bin/rector process src --dry-run
  

• Partial Runs: Target specific files/directories:

  vendor/bin/rector process app/Http/Controllers --dry-run
  

• Combine with PHPStan: Use --parallel for faster execution:

  vendor/bin/rector process src --parallel
  

Gotchas and Tips

Pitfalls

1. Dry Runs First:

   • Always use --dry-run before applying changes to avoid breaking builds.
   • Example:

     vendor/bin/rector process src --dry-run --format=diff
     

2. Facade Aliases:

   • LaravelSetList::LARAVEL_FACADE_ALIASES_TO_FULL_NAMES may break tests using aliases like Auth::user().
   • Fix: Exclude test files or manually update assertions.

3. Route Callables:

   • RouteActionCallableRector requires NAMESPACE config for custom controller paths:

     ->withConfiguredRule(RouteActionCallableRector::class, [
         'NAMESPACE' => 'App\\Http\\Controllers\\Admin\\',
     ])
     

4. Type Declarations:

   • LaravelSetList::LARAVEL_TYPE_DECLARATIONS may fail on dynamic properties (e.g., __get()).
   • Fix: Exclude problematic classes:

     ->withExcludedPaths([__DIR__.'/app/Helpers/DynamicProperty.php'])
     

Debugging

• Verbose Output:

  vendor/bin/rector process src --verbose
  

• Rule-Specific Debugging: Disable individual rules to isolate issues:

  ->withRules([]) // Start empty, then add rules one by one
  

Config Quirks

1. PostgreSQL vs MySQL:

   • WhereToWhereLikeRector requires USING_POSTGRES_DRIVER for PostgreSQL:

     ->withConfiguredRule(WhereToWhereLikeRector::class, [
         'USING_POSTGRES_DRIVER' => true,
     ])
     

2. Excluding Files:

   • Use withExcludedPaths() or withExcludedNodes():

     ->withExcludedPaths([__DIR__.'/vendor/', __DIR__.'/tests/'])
     

3. Custom Rules:

   • Test new rules in isolation:

     vendor/bin/rector process src --rules=YourRuleName
     

Extension Points

1. Create Custom Rules:

   composer make:rule -- YourCustomRuleName
   

   • Example: Convert Str::of($str)->upper() → Str::upper($str).

2. Override Default Sets:

   ->withSets([
       LaravelSetList::LARAVEL_CODE_QUALITY,
       // Override a specific rule
       new class implements RectorSet {
           public function getRules(RectorConfig $config): array {
               return [new YourCustomRector()];
           }
       },
   ])
   

3. Parallel Processing:

   • Speed up large codebases:

     vendor/bin/rector process src --parallel --max-workers=4
     

Pro Tips

• Pre-Commit Hook:

  echo 'vendor/bin/rector process src --dry-run' >> .git/hooks/pre-commit
  

• Git Diff Integration: Use --format=diff to review changes in Git:

  vendor/bin/rector process src --dry-run --format=diff | git apply --check
  

• IDE Support: After running Rector, refresh your IDE’s metadata (e.g., PHPStorm: File > Invalidate Caches).