Typo3 Rector Laravel Package

Technical Evaluation

Architecture Fit

• TYPO3-Specific Refactoring: The package is tightly coupled with TYPO3’s ecosystem (e.g., TCA, TypoScript, Fluid templates, and core class migrations). It leverages Rector’s AST-based transformation to automate PHP refactoring, making it ideal for large-scale TYPO3 upgrades (e.g., v10 → v14) where manual migration is error-prone.
• Modular Rule Sets: Rules are organized by TYPO3 version (e.g., TYPO3_12, TYPO3_13) and category (e.g., TCA, TypeDeclaration, CodeQuality), allowing granular application (e.g., migrate TCA first, then core classes).
• ClassAliasMap Integration: Supports backward-compatible class migrations via TYPO3’s ClassAliasMap, critical for skipping intermediate versions (e.g., v8 → v10).
• Non-PHP File Limitations: v2+ focuses solely on PHP files (v1 supported TypoScript/FlexForm), which may require complementary tools (e.g., fractor) for full stack migrations.

Integration Feasibility

• Composer-Based: Seamless integration via composer require --dev ssch/typo3-rector, with zero runtime dependencies (dev-only).
• Rector Ecosystem: Builds on Rector’s existing infrastructure (e.g., dry-run, parallel processing), reducing learning curve for teams familiar with PHP refactoring tools.
• TYPO3 Compatibility: Works with PHP 7.4+ and TYPO3 v10–v14 (v1 supports v7–v12). Requires TYPO3’s class-alias-loader for class migrations.
• CI/CD Friendly: Can be gated in PRs (dry-run) or automated in pipelines (e.g., post-merge to staging).

Technical Risk

• False Positives/Negatives: AST-based refactoring may miss edge cases (e.g., custom TCA overrides without ctrl/columns). Requires manual review for critical paths.
• Coding Standard Dependencies: Output code loses formatting (e.g., docblocks, spacing). ECS/Symfony CS Fixer must be configured post-rector.
• ClassAliasMap Complexity: Skipping versions (e.g., v8 → v10) requires manual composer.json updates with correct ClassAliasMap paths.
• Stateful Rules: Some rules (e.g., AddAutoconfigureAttributeToClassRector) require pre-rector setup (e.g., generating Symfony container XML).
• TYPO3-Specific Knowledge: Rules assume standard TYPO3 patterns (e.g., ext_emconf.php structure). Custom extensions may need rule exclusions.

Key Questions

1. Scope of Migration:
   • Are you upgrading core TYPO3, extensions, or both? Rules may need separate execution (e.g., TCA-first for extensions).
   • Do you need to skip versions (e.g., v10 → v12)? If so, ClassAliasMap must be pre-configured.
2. Testing Strategy:
   • How will you validate refactored code? Dry-run + unit tests are recommended.
   • Are there critical paths (e.g., custom TCA, hooks) that require manual review?
3. Toolchain Integration:
   • Will you use ECS/Symfony CS Fixer post-rector? If not, code quality may degrade.
   • Do you need to migrate non-PHP files (e.g., TypoScript)? Complement with fractor or manual steps.
4. Performance:
   • For large codebases, parallel processing (--parallel) may be needed.
   • Will CI/CD pipelines support the refactoring step (e.g., timeouts, resource limits)?
5. Rollback Plan:
   • How will you revert accidental changes? Version control (e.g., Git) is mandatory.

Integration Approach

Stack Fit

• Primary Use Case: TYPO3 PHP codebase modernization (e.g., upgrading extensions/core, removing deprecations).
• Complementary Tools:
  • ECS/Symfony CS Fixer: Enforce coding standards post-rector.
  • fractor: Handle TypoScript/FlexForm migrations (if using v1).
  • PHPStan/Psalm: Static analysis to catch post-rector issues.
• IDE Support: Works with PHPStorm (via Rector plugin) for real-time refactoring previews.

Migration Path

1. Assessment Phase:
   • Run vendor/bin/rector process --dry-run to identify changes before execution.
   • Review rule exclusions (e.g., --exclude-paths) for custom code.
2. Configuration:
   • Generate config: vendor/bin/typo3-init.
   • Define rule sets by version (e.g., Typo3SetList::TYPO3_12).
   • Add ClassAliasMap to composer.json if skipping versions.
3. Execution:
   • Incremental Approach: Apply rules version-by-version (e.g., v10 → v11 → v12).
   • Parallel Processing: Use --parallel for large codebases.
   • Post-Rector: Run ECS to reformat code.
4. Validation:
   • Unit Tests: Ensure refactored code passes existing tests.
   • Manual Review: Focus on critical paths (e.g., custom TCA, hooks).

Compatibility

• PHP Version: 7.4+ (required by Rector).
• TYPO3 Version: v10–v14 (v1 supports v7–v12). Ensure composer.json constraints align.
• Dependency Conflicts: Rare, but Rector’s core dependencies (e.g., php-parser) must not conflict with project dependencies.
• Custom Extensions: May require rule exclusions or manual overrides for non-standard patterns.

Sequencing

1. Pre-Rector Setup:
   • Install package: composer require --dev ssch/typo3-rector.
   • Configure composer.json (e.g., ClassAliasMap, PHP version).
   • Generate config: vendor/bin/typo3-init.
2. Rule Application Order:
   • Oldest → Newest: Apply rules chronologically (e.g., v10 → v11 → v12).
   • TCA-First: Migrate TCA structures before core classes.
   • Separate Packages: Group extensions by version/dependency to avoid conflicts.
3. Post-Rector:
   • Run ECS/Symfony CS Fixer.
   • Update composer.json (e.g., constraints, autoload).
   • Clear caches: vendor/bin/typo3 cache:flush.

Operational Impact

Maintenance

• Long-Term Viability:
  • Active Development: Project is MIT-licensed with regular updates (last release: 2026-03-10).
  • Community Support: Slack channel (#ext-typo3-rector) and GitHub issues for troubleshooting.
• Rule Updates:
  • New TYPO3 versions may require new rule sets (e.g., Typo3SetList::TYPO3_15).
  • Deprecation: Rules for older versions (e.g., v7–v9) may be removed in future updates.
• Custom Rules:
  • Extend with custom Rector rules if standard rules are insufficient.

Support

• Troubleshooting:
  • Dry-Run: Always use --dry-run to debug issues before applying changes.
  • Logs: Rector provides detailed diffs for manual review.
  • Slack/GitHub: Community support for TYPO3-specific edge cases.
• Documentation:
  • Comprehensive: Covers installation, configuration, and best practices.
  • Examples: Includes real-world migration scenarios (e.g., v10 → v12).
• Training:
  • Rector Basics: Familiarity with AST transformations helps avoid pitfalls.
  • TYPO3 Internals: Understanding TCA, TypoScript, and class structures is critical.

Scaling

• Large Codebases:
  • Parallel Processing: Use --parallel to speed up execution.
  • Incremental Migrations: Break into smaller batches (e.g., per extension).
• Performance:
  • Memory Usage: AST parsing can