Rector Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer in your Laravel project:

   composer require --dev contao/rector
   

   Ensure rector/rector is also installed (required dependency).

2. Basic Setup Create a rector.php config file in your project root (or extend an existing one):

   <?php
   declare(strict_types=1);
   
   use Rector\Core\Configuration\Option;
   use Rector\Core\ValueObject\PhpVersion;
   use Symplify\EasyTesting\Parameter\ParameterProvider;
   
   $rectorConfig = new RectorConfig();
   $rectorConfig->paths([
       __DIR__ . '/app',
       __DIR__ . '/tests',
   ]);
   
   $rectorConfig->phpVersion(PhpVersion::PHP_80);
   
   // Load Contao-specific rules
   $rectorConfig->importNames();
   $rectorConfig->importShortClasses();
   $rectorConfig->import(contao\Rector\Set\ContaoSetList::CONTAO_40);
   
   return $rectorConfig;
   

3. First Use Case Run Rector to auto-fix Contao-specific code:

   vendor/bin/rector process
   

   Focus on Contao 4.x compatibility if migrating or maintaining legacy code.

Implementation Patterns

Workflows

1. Legacy Code Modernization Use CONTAO_40 set to update Contao 3.x syntax to Contao 4.x standards:

   $rectorConfig->import(contao\Rector\Set\ContaoSetList::CONTAO_40);
   

   • Targets: tl_* table references, tl_* prefix removal, tl_* to Model\* conversions.

2. Laravel-Contao Integration Combine with Laravel’s illuminate/support rules for hybrid projects:

   $rectorConfig->import(Rector\Set\LaravelSetList::LARAVEL_80);
   $rectorConfig->import(contao\Rector\Set\ContaoSetList::CONTAO_40);
   

3. Custom Rule Extension Extend Contao rules for project-specific needs:

   $rectorConfig->ruleWithConfiguration(
       new contao\Rector\Rename\RenameTlModelToModel(),
       [new ParameterProvider('tl_article', 'Model\Article')]
   );
   

Integration Tips

• CI/CD Pipelines: Run Rector in a GitHub Action for pre-commit checks:

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

• Partial Processing: Target specific files/directories:

  $rectorConfig->paths([__DIR__ . '/app/Http/Controllers/Contao']);
  

• Dry Runs: Always test changes first:

  vendor/bin/rector process --dry-run
  

Gotchas and Tips

Pitfalls

1. Over-Aggressive Refactoring

   • Issue: Blindly applying CONTAO_40 rules may break custom Contao extensions.
   • Fix: Use --dry-run and review changes manually. Exclude vendor paths:

     $rectorConfig->excludePaths([__DIR__ . '/vendor']);
     

2. PHP Version Mismatch

   • Issue: Contao rules assume PHP 8.0+. Errors may occur on PHP 7.4.
   • Fix: Set correct PHP version in config:

     $rectorConfig->phpVersion(PhpVersion::PHP_74);
     

3. Database Schema Dependencies

   • Issue: Rules like tl_* to Model\* require matching database tables.
   • Fix: Run database migrations or mock models in tests before refactoring.

Debugging

• Verbose Output: Enable for detailed rule execution:

  vendor/bin/rector process --verbose
  

• Rule Isolation: Test individual rules:

  vendor/bin/rector process --rule=contao\Rector\Rename\RenameTlModelToModel
  

Extension Points

1. Custom Rules Extend contao\Rector\Set\ContaoSetList by creating a new rule class:

   namespace App\Rector;
   
   use PhpParser\Node;
   use Rector\Core\Rector\AbstractRector;
   
   class CustomContaoRector extends AbstractRector {
       public function refactor(Node $node): ?Node {
           // Custom logic here
       }
   }
   

   Register it in rector.php:

   $rectorConfig->rule(new \App\Rector\CustomContaoRector());
   

2. Configuration Overrides Override Contao rules via rector.php:

   $rectorConfig->ruleWithConfiguration(
       new contao\Rector\Rename\RenameTlModelToModel(),
       [new ParameterProvider('tl_', 'CustomPrefix\')]
   );
   

3. Parallel Processing Speed up large codebases with parallel execution:

   $rectorConfig->parallel();