Contao Rector Laravel Package

Getting Started

Minimal Steps

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

   composer require --dev contao/contao-rector
   

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

2. Basic Setup Configure Rector in rector.php (create if missing):

   use Contao\Rector\ContaoSetList;
   use Rector\Core\Configuration\Option;
   
   return [
       Option::SET_LISTS => [
           ContaoSetList::CONTAO_4_13,
       ],
       Option::AUTO_IMPORT_NAMES => true,
   ];
   

3. First Use Case Run Rector on a Contao-specific file (e.g., a custom tl_content class):

   vendor/bin/rector process src/Contao
   

   Verify changes with Git diff or git status.

Implementation Patterns

Workflow Integration

1. Pre-Commit Hook Add Rector to your CI/CD or Git hooks (e.g., .github/workflows/rector.yml):

   jobs:
     rector:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer require --dev contao/contao-rector
         - run: vendor/bin/rector process --dry-run
   

2. Laravel-Specific Patterns

   • Service Container Integration: Use Rector to update Contao service container bindings in Laravel’s AppServiceProvider:

     // Before
     $this->app->bind('contao.model', function() { ... });
     
     // After (auto-updated by Rector)
     $this->app->singleton('contao.model', function() { ... });
     

   • Event Listeners: Convert Contao’s onLoad callbacks to Laravel’s booted events:

     // Before
     System::registerCallback(['MyClass', 'handleEvent']);
     
     // After (Rector-generated)
     Event::listen('contao.load', [MyClass::class, 'handleEvent']);
     

3. Partial Runs Target specific files/directories for incremental updates:

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

Gotchas and Tips

Pitfalls

1. Contao Version Mismatch

   • Rector rules are version-specific (e.g., CONTAO_4_13). Running on CONTAO_4_12 may fail or produce incorrect output.
   • Fix: Explicitly set the correct ContaoSetList in rector.php.

2. False Positives in Legacy Code

   • Rector may flag Contao’s core files (e.g., system/config/autoload.php) as outdated.
   • Fix: Exclude core files via Option::EXCLUDE_PATHS:

     Option::EXCLUDE_PATHS => [__DIR__.'/vendor/contao/core'],
     

3. Database Awareness

   • Rector won’t update database tables (tl_*) or DCA configurations. Manual review is required for schema changes.

Debugging

• Dry Runs: Always use --dry-run first to preview changes:

  vendor/bin/rector process --dry-run
  

• Verbose Output: Enable debug mode for rule-specific logs:

  vendor/bin/rector process -vvv
  

Extension Points

1. Custom Rules Extend Rector with Contao-specific rules by creating a custom rule set:

   // config/rector.php
   Option::RULES => [
       new Set\RectorSet([new Rule\YourCustomContaoRule()]),
   ];
   

2. Laravel Contao Hybrid Projects Use Rector to bridge Contao’s tl_* table access with Laravel’s Eloquent:

   // Before (Contao)
   $model = Model::findByPk(42);
   
   // After (Rector + custom rule)
   $model = \App\Models\Contao\Page::find(42);
   

3. Configuration Quirks

   • Caching: Rector caches rule sets. Clear cache after updating rector.php:

     vendor/bin/rector clear-cache
     

   • PHP Version: Ensure your PHP version matches Contao’s requirements (e.g., 8.1+ for Contao 4.13).