Contao Rector Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The contao/contao-rector package provides Rector rules tailored for Contao CMS, a PHP-based content management system. It enables automated refactoring of legacy Contao codebases (e.g., PHP 7.4 → PHP 8.1+) while preserving Contao-specific patterns (e.g., tl_* database tables, DCA structures, hooks, and legacy syntax).
• Core Use Case: Ideal for modernizing Contao applications without manual rewrites, reducing technical debt while maintaining backward compatibility during transitions.
• Non-Fit Scenarios:
  • Non-Contao PHP projects (e.g., Laravel, Symfony) will gain no direct value unless Contao-specific code exists.
  • Greenfield projects may not need legacy refactoring, though Rector’s general rules could still apply.

Integration Feasibility

• Dependency Graph:
  • Requires Rector (rector/rector) as a base tool (PHP 8.0+).
  • Contao-specific rules extend Rector’s core, so integration is lightweight (no Contao installation needed for rule application).
  • Potential Conflicts: If the target codebase uses custom Contao extensions or non-standard naming conventions, rules may need adjustment.
• Toolchain Compatibility:
  • Works with PHPUnit, PHPStan, and PSR-12 codebases (Contao’s default).
  • CI/CD Friendly: Can be run as a pre-commit hook or GitHub Actions step for incremental refactoring.

Technical Risk

Key Questions for TPM

1. Codebase Scope:
   • What percentage of the codebase is Contao-specific (vs. custom PHP/Laravel logic)?
   • Are there custom DCA fields, hooks, or legacy template syntax that might break?
2. Refactoring Goals:
   • Is the target PHP version upgrade (e.g., 7.4 → 8.2) or general cleanup?
   • Are there specific Contao features (e.g., tl_content elements) that need preservation?
3. Tooling Integration:
   • How will Rector fit into the existing CI/CD pipeline (e.g., alongside PHPStan, Pest)?
   • Should it run pre-commit (for developers) or post-merge (for CI)?
4. Stakeholder Alignment:
   • Do developers need training on Rector’s output (e.g., understanding generated code)?
   • How will QA/testers verify refactored functionality (e.g., regression testing)?

Integration Approach

Stack Fit

• Primary Use Case: Contao CMS (PHP 7.4–8.2+) with legacy codebases.
• Secondary Use Case: Hybrid PHP apps with Contao modules/plugins (e.g., a Laravel app using Contao’s backend).
• Non-Fit:
  • Non-Contao PHP frameworks (Laravel/Symfony) unless Contao-specific logic exists.
  • JavaScript/TypeScript or non-PHP components.

Migration Path

1. Assessment Phase:
   • Audit the codebase for Contao-specific patterns (e.g., tl_* tables, {$var} syntax, \Contao\* classes).
   • Identify high-risk areas (e.g., custom hooks, legacy template files).
2. Pilot Run:
   • Apply Rector in dry-run mode (--dry-run) to preview changes.
   • Test on a forked branch with automated tests (PHPUnit + Contao’s Behat).
3. Incremental Rollout:
   • Start with low-risk rules (e.g., PHP 8.1 syntax updates).
   • Gradually enable Contao-specific rules (e.g., tl_content refactoring).
4. Final Validation:
   • Run full test suite (unit + integration).
   • Manual review of critical paths (e.g., checkout flow, backend modules).

Compatibility

Sequencing

1. Pre-Refactor:
   • Backup the database and codebase.
   • Set up a staging environment mirroring production.
2. Rule Application:
   • Run Rector with Contao rules first, then generic PHP rules.
   • Example command:

     vendor/bin/rector process src --dry-run --rules="[Contao\Rector\Set\Contao74Set]"
     

3. Post-Refactor:
   • Update Composer dependencies (e.g., contao/core-bundle to PHP 8.1+ compatible version).
   • Rebuild asset pipelines (if using Contao’s assets system).
4. Deployment:
   • Deploy to staging first; monitor for degraded performance or missing features.
   • Roll back if critical issues arise (e.g., backend module failures).

Operational Impact

Maintenance

• Ongoing Costs:
  • Minimal: Rector rules are idempotent (can be re-run safely).
  • Rule Updates: Monitor contao/contao-rector for new Contao versions (e.g., Contao 5.x rules).
• Dependency Management:
  • Pin Rector version in composer.json to avoid breaking changes.
  • Example:

    "require-dev": {
      "rector/rector": "^0.15",
      "contao/contao-rector": "^1.0"
    }
    

Support

• Developer Onboarding:
  • Train team on reading Rector’s diff output (e.g., understanding tl_content refactoring).
  • Document excluded files/directories (e.g., vendor/, templates/).
• Troubleshooting:
  • Common Issues:
    • False positives in custom DCA fields.
    • Deprecated Contao hooks (e.g., onLoadTemplate → onLoad).
  • Debugging Tools:
    • Use --show-skipped to identify unprocessed files.
    • Check Rector’s rector.log for errors.

Scaling

• Performance:
  • Large Codebases (>50K LOC): Use --parallel=4 to speed up execution.
  • CI Timeouts: Run Rector in separate jobs (e.g., GitHub Actions matrix).
• Parallelization:
  • Split rules by file type (e.g., models/ → PHP 8.1 rules, dca/ → Contao-specific rules).
• Incremental Adoption:
  • Refactor one module/extension at a time to isolate risks.

Failure Modes