Rector Laravel Laravel Package

Getting Started

Minimal Steps

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. Run Rector:

   vendor/bin/rector process src
   

First Use Case

Upgrade Laravel 12 → 13:

composer require --dev driftingly/rector-laravel
vendor/bin/rector process src --dry-run  # Preview changes
vendor/bin/rector process src           # Apply changes

Implementation Patterns

Workflows

1. Version-Specific Upgrades: Use LaravelSetProvider for automatic version detection or manually specify sets:

   ->withSets([
       LaravelLevelSetList::UP_TO_LARAVEL_130,  // Covers 12→13
       LaravelLevelSetList::LARAVEL_130,        // Only 12→13 changes
   ])
   

2. Code Quality Improvements: Combine version upgrades with quality sets:

   ->withSets([
       LaravelLevelSetList::UP_TO_LARAVEL_130,
       LaravelSetList::LARAVEL_CODE_QUALITY,
       LaravelSetList::LARAVEL_COLLECTION,
   ])
   

3. Testing-Focused Refinements:

   ->withSets([
       LaravelSetList::LARAVEL_TESTING,
       LaravelSetList::LARAVEL_TYPE_DECLARATIONS,
   ])
   

Integration Tips

• CI/CD Pipeline: Add to php-cs-fixer/rector step in GitHub Actions:

  - name: Run Rector
    run: vendor/bin/rector process src --dry-run
  

• Pre-Commit Hook: Use rector with php-cs-fixer via roave/security-advisories or custom script.
• Partial Runs: Target specific files/directories:

  vendor/bin/rector process app/Http/Controllers --set LaravelSetList::LARAVEL_STATIC_TO_INJECTION
  

Gotchas and Tips

Pitfalls

1. Dry-Run First: Always use --dry-run to preview changes before applying:

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

   • Fix: Review diffs for unexpected changes (e.g., dd() removals in tests).

2. Facade → DI Migration: LaravelSetList::LARAVEL_STATIC_TO_INJECTION may break:

   • Tests: Mock dependencies explicitly.
   • Services: Update constructor injections (e.g., Cache → Illuminate\Contracts\Cache\Repository).

3. Collection Method Conflicts: LaravelSetList::LARAVEL_COLLECTION may clash with custom methods:

   • Fix: Exclude specific files:

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

4. Route Action Strings: RouteActionCallableRector requires namespace config:

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

Debugging

• Verbose Output:

  vendor/bin/rector process src --verbose
  

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

  ->withSkip([
      \RectorLaravel\Rector\MethodCall\WhereToWhereLikeRector::class,
  ])
  

Extension Points

1. Custom Rules: Generate and extend rules:

   composer make:rule -- If_/ConvertLegacyAuthToSanctum
   

   • Example: Target Auth::user() → auth()->user() in legacy code.

2. Conditional Rules: Use Rector\Contract\Rector\ConfigurableRectorInterface for dynamic behavior:

   class CustomCacheRector implements ConfigurableRectorInterface {
       public function __construct(public bool $useSeconds) {}
       // ...
   }
   

3. Post-Rector Hooks: Chain with php-cs-fixer or pestphp/pest for final formatting:

   vendor/bin/rector process src && vendor/bin/php-cs-fixer fix
   

Pro Tips

• Exclude Tests:

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

• Target Specific Versions: Use dev-main branch for unreleased rules:

  composer require driftingly/rector-laravel:dev-main --dev
  

• Monitor Changes: Track Rector’s rector.log for skipped files/rules:

  ->withAutoloadPaths([__DIR__.'/vendor'])