Typo3 Rector Laravel Package

Technical Evaluation

Architecture Fit

• Target Use Case: The package is not a Laravel/PHP package but a TYPO3-specific Rector for automated code migration/refactoring. It extends the Rector framework to handle TYPO3 deprecations, upgrades, and refactoring (e.g., Fluid templates, TypoScript, Extbase, TCA).
• Laravel Relevance:
  • Low Direct Fit: Laravel and TYPO3 are distinct ecosystems (Laravel = modern PHP framework; TYPO3 = legacy CMS).
  • Indirect Use Cases:
    • If your Laravel project integrates with TYPO3 (e.g., via APIs, legacy migration, or hybrid setups), this could help modernize TYPO3-specific PHP codebases before integration.
    • For TYPO3-to-Laravel migration projects, this could pre-process TYPO3 code to reduce manual refactoring effort.
  • Core Value: Primarily useful for TYPO3 maintainers or teams migrating from older TYPO3 versions (e.g., v10→v14).

Integration Feasibility

• Dependencies:
  • Requires PHP 7.4+ (compatible with Laravel’s min PHP 8.0+ in most cases).
  • Depends on Rector (a separate PHP package) and TYPO3-specific rules (e.g., Fluid, Extbase, TCA).
  • No Laravel-specific hooks/plugins: Runs as a standalone CLI tool (vendor/bin/rector process).
• Laravel Compatibility:
  • No conflicts with Laravel’s core, but no native Laravel support (e.g., no Laravel-specific rectors).
  • Could be chained with Laravel’s own tools (e.g., pest, phpstan, or robo) for hybrid workflows.
• File Scope:
  • v3+: PHP-only (no TypoScript/FlexForm/Fluid in v3+; use fractor for those).
  • Laravel projects won’t benefit from TYPO3-specific rules (e.g., MigrateTypoScriptFrontendControllerConfigRector).

Technical Risk

• False Positives:
  • Rector’s AST-based approach may misinterpret Laravel-specific patterns (e.g., Facades, Blade-like syntax in TYPO3 templates).
  • Risk: Running on Laravel code could break non-TYPO3 logic (e.g., custom helpers, legacy PHP).
• Performance:
  • Heavy refactoring (e.g., UseStrictTypesInFluidViewHelpersRector) may slow down CI/CD pipelines if misconfigured.
• Maintenance Overhead:
  • Requires manual review of changes (as warned in the README).
  • No Laravel-specific safety nets: Unlike Laravel’s php artisan optimize, this tool lacks project-aware safeguards.

Key Questions for a TPM

1. Why Laravel?
   • Is this for TYPO3-Laravel interop (e.g., migrating a TYPO3 backend to Laravel)?
   • Or is there a misalignment (e.g., evaluating the wrong tool for Laravel’s needs)?
2. Scope of Use:
   • Will this replace Laravel’s native tools (e.g., phpstan, pest)? If so, what’s the ROI?
   • Are you targeting legacy PHP code (not Laravel-specific) that could benefit from Rector’s general rules?
3. Alternatives:
   • For Laravel: Consider Rector’s PHP rules (no TYPO3 bloat).
   • For TYPO3: Use fractor for non-PHP files (TypoScript, Fluid).
4. Process Safety:
   • How will you validate changes before merging? (e.g., automated tests, manual PR reviews).
   • What’s the rollback plan if Rector introduces bugs?

Integration Approach

Stack Fit

• Laravel Stack:
  • Not a direct fit: Laravel’s ecosystem (Lumen, Livewire, Forge) has no native TYPO3 dependencies.
  • Potential Niche Use:
    • Legacy Migration: If Laravel is consuming a TYPO3 API or replacing a TYPO3 backend, this could pre-process TYPO3 PHP code.
    • Hybrid Projects: For projects with mixed TYPO3/Laravel codebases (e.g., a Laravel frontend + TYPO3 CMS backend).
• Toolchain Placement:
  • Pre-Commit Hook: Run in CI/CD (GitHub Actions/GitLab CI) as a gated step (e.g., fail builds if dry-run shows critical changes).
  • Local Dev: Add to composer.json scripts:

    "scripts": {
      "typo3:rector": "vendor/bin/rector process --dry-run",
      "typo3:migrate": "vendor/bin/rector process"
    }
    

  • Parallel with Laravel Tools:

    composer run typo3:rector && composer test
    

Migration Path

1. Assess Codebase:
   • Audit for TYPO3-specific patterns (e.g., GeneralUtility, Fluid templates, Extbase).
   • Use rector process --dry-run to identify safe vs. risky changes.
2. Phased Rollout:
   • Phase 1: Run on TYPO3-only modules (if any) to validate.
   • Phase 2: Gradually apply to shared PHP files (if applicable).
   • Phase 3: Integrate with Laravel’s testing pipeline (e.g., run Rector in a Docker container).
3. Configuration:
   • Customize rector.php to exclude Laravel-specific files (e.g., app/, resources/).
   • Example:

     return static::configure()
         ->withPaths([
             __DIR__.'/typo3-extensions/', // Only TYPO3 code
         ])
         ->withRule(MigrateTypoScriptFrontendControllerConfigRector::class);
     

Compatibility

• Laravel-Specific Risks:
  • Facades: TYPO3 rectors may misinterpret Laravel’s Facade calls (e.g., Auth::user()).
  • Blade/Templating: Fluid-specific rectors (e.g., UseStrictTypesInFluidViewHelpersRector) won’t work in Laravel Blade.
  • Dependencies: Conflicts possible if TYPO3 and Laravel share vendor namespaces (e.g., TYPO3\CMS\* vs. Laravel\*).
• Mitigations:
  • Use --exclude-paths to avoid Laravel directories.
  • Test in isolation: Run Rector on a copy of the codebase first.

Sequencing

1. Pre-requisites:
   • Install Rector and ssch/typo3-rector in a dev dependency:

     composer require --dev rector/rector ssch/typo3-rector
     

   • Set up ECS (Easy Coding Standard) for post-Rector formatting (as per the package’s warning).
2. Order of Operations:
   • Step 1: Run typo3-init to generate config.
   • Step 2: Dry-run (--dry-run) on a subset of files.
   • Step 3: Merge changes incrementally (e.g., per PR).
   • Step 4: Add to CI as a gated check.
3. Post-Integration:
   • Monitor performance impact in CI/CD.
   • Document excluded paths and manual overrides in README.md.

Operational Impact

Maintenance

• Ongoing Effort:
  • Configuration Drift: Rector rules may need updates if TYPO3/Laravel dependencies change.
  • Dependency Management:
    • ssch/typo3-rector is actively maintained (last release: 2026-04-13), but Laravel’s ecosystem evolves faster.
    • Risk: Future Laravel versions may introduce breaking changes that Rector’s TYPO3 rules don’t account for.
• Toolchain Complexity:
  • Adds another tool to maintain (Rector + ECS + Laravel’s tools).
  • Documentation Burden: Teams must learn Rector’s dry-run, rule configuration, and CI integration.

Support

• Troubleshooting:
  • False Positives: Laravel devs may blame Rector for "breaking" their code (e.g., misapplied UseStrictTypes).
  • TYPO3-Specific Issues: Support queries will require TYPO3 expertise (e.g., "Why did GeneralUtility