TYPO3 Rector Upgrade Patterns
Compatibility: TYPO3 v13.x and v14.x (v14 preferred) This skill covers patterns for writing code that works on both v13 and v14.
- Introduction to TYPO3 Rector
Rector is an automated refactoring tool that helps migrate TYPO3 extensions between major versions. It applies predefined rules to update deprecated code patterns.
Installation ddev composer require --dev ssch/typo3-rector
Basic Configuration for Dual-Version Support
Create rector.php in your project root:
withPaths([ __DIR__ . '/packages', __DIR__ . '/public/typo3conf/ext', ]) ->withSkip([ __DIR__ . '/public/typo3conf/ext/*/Resources/', __DIR__ . '/public/typo3conf/ext/*/Tests/', ]) ->withPhpVersion(PhpVersion::PHP_82) ->withSets([ // PHP upgrades LevelSetList::UP_TO_PHP_82, // TYPO3 v13 minimum (works on v14 too) Typo3LevelSetList::UP_TO_TYPO3_13, ]) ->withImportNames(); 2. Running Rector Dry Run (Preview Changes) # Show what would be changed ddev exec vendor/bin/rector process --dry-run # For specific extension ddev exec vendor/bin/rector process packages/my_extension --dry-run Apply Changes # Apply all changes ddev exec vendor/bin/rector process # Apply to specific path ddev exec vendor/bin/rector process packages/my_extension Clear Cache After ddev typo3 cache:flush ddev composer dump-autoload 3. Dual-Version Compatible Patterns Version Constraints For extensions that must work on both v13 and v14: 'My Extension', 'version' => '2.0.0', 'state' => 'stable', 'constraints' => [ 'depends' => [ 'typo3' => '13.0.0-14.99.99', 'php' => '8.2.0-8.4.99', ], 'conflicts' => [], 'suggests' => [], ], ]; // composer.json { "require": { "php": "^8.2", "typo3/cms-core": "^13.0 || ^14.0" } } Rector Configuration for v13/v14 Dual Support withPaths([__DIR__ . '/packages']) ->withSets([ // Target v13 minimum - these patterns also work on v14 Typo3LevelSetList::UP_TO_TYPO3_13, Typo3SetList::TYPO3_13, ]); 4. Key Migration Patterns (v13/v14 Compatible) Fluid ViewFactory (Replaces StandaloneView) The ViewFactory approach works on both v13 and v14: viewFactory->create($viewFactoryData); $view->assign('data', ['key' => 'value']); $view->assignMultiple([ 'items' => [], 'settings' => [], ]); return $view->render('MyTemplate'); } } ExtBase Controller Response (Required in v13+) itemRepository->findAll(); $this->view->assign('items', $items); return $this->htmlResponse(); } // ✅ Correct: JSON response public function apiAction(): ResponseInterface { $data = ['success' => true]; return $this->jsonResponse(json_encode($data)); } // ✅ Correct: Redirect public function createAction(Item $item): ResponseInterface { $this->itemRepository->add($item); return $this->redirect('list'); } } PSR-14 Events (Preferred over Hooks) PSR-14 events work on both v13 and v14. Use them instead of legacy hooks: getConfiguration(); // Modify link configuration $event->setConfiguration($configuration); } } Backend Module Registration (v13/v14) [ 'parent' => 'web', 'position' => ['after' => 'web_info'], 'access' => 'user,group', 'iconIdentifier' => 'myextension-module', 'path' => '/module/web/myextension', 'labels' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_mod.xlf', 'extensionName' => 'MyExtension', 'controllerActions' => [ \Vendor\MyExtension\Controller\ModuleController::class => [ 'index', 'edit', ], ], ], ]; Service Configuration (Services.yaml) # Configuration/Services.yaml services: _defaults: autowire: true autoconfigure: true public: false Vendor\MyExtension\: resource: '../Classes/*' exclude: - '../Classes/Domain/Model/*' 5. TCA Best Practices (v13/v14) Static TCA Only In v14, $GLOBALS['TCA'] becomes read-only after loading. Always use static TCA files: 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:mytype.title', 'value' => 'myextension_mytype', 'icon' => 'content-text', 'group' => 'default', ] ); $GLOBALS['TCA']['tt_content']['types']['myextension_mytype'] = [ 'showitem' => ' --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:general, --palette--;;general, header;LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:header_formlabel, bodytext, --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access, --palette--;;hidden, --palette--;;access, ', 'columnsOverrides' => [ 'bodytext' => [ 'config' => [ 'enableRichtext' => true, ], ], ], ]; 6. Version Compatibility Table Feature TYPO3 v13 TYPO3 v14 Notes PHP 8.2 Required Required Minimum for both PHP 8.3 Supported Supported Recommended PHP 8.4 Supported Supported Available Symfony 7 7.1 7.2 Minor differences PSR-14 Events Full Full Preferred pattern Legacy Hooks Working Deprecated Migrate to events ViewFactory Available Available Use this approach StandaloneView Deprecated Removed Migrate now Content Blocks Available Enhanced New features in v14 TCA Runtime Changes Deprecated Forbidden Use static TCA only 7. Step-by-Step Migration Process 1. Prepare # Create backup ddev snapshot --name=before-migration # Ensure tests pass ddev exec vendor/bin/phpunit -c packages/my_extension/Tests/phpunit.xml # Check deprecation log tail -f var/log/typo3_deprecations_*.log 2. Configure Rector for Dual-Version withPaths([__DIR__ . '/packages/my_extension/Classes']) ->withSets([ Typo3LevelSetList::UP_TO_TYPO3_13, ]); 3. Run Rector # Dry run first ddev exec vendor/bin/rector process --dry-run # Apply changes ddev exec vendor/bin/rector process # Review changes git diff 4. Manual Fixes Review Rector output for skipped files Check deprecation log for remaining issues Update TCA configurations manually Test all backend modules 5. Test on Both Versions # Test on v13 ddev composer require "typo3/cms-core:^13.0" --no-update ddev composer update ddev typo3 cache:flush # Run tests ddev exec vendor/bin/phpunit # Test on v14 ddev composer require "typo3/cms-core:^14.0" --no-update ddev composer update ddev typo3 cache:flush # Run tests again ddev exec vendor/bin/phpunit 6. Commit git add -A git commit -m "feat: Add TYPO3 v13/v14 dual-version support" 8. Troubleshooting Rector Fails # Clear Rector cache rm -rf .rector_cache/ # Run with verbose output ddev exec vendor/bin/rector process --dry-run -vvv Extension Incompatibility Check for updates: ddev composer outdated ddev composer show -l Search for v13/v14-compatible alternatives on: https://extensions.typo3.org https://packagist.org Database Issues # Check schema differences ddev typo3 database:updateschema --verbose # Safe schema update (add only) ddev typo3 database:updateschema "*.add,*.change" # Full update (includes destructive) ddev typo3 database:updateschema "*" 9. Common Rector Rules Namespace Changes (Auto-Migrated) Rector automatically handles namespace changes between versions. Utility Method Changes getAttribute('normalizedParams'); $host = $normalizedParams->getRequestHost(); ObjectManager Removal get(MyService::class); // ✅ New (Dependency Injection) public function __construct( private readonly MyService $myService, ) {} 10. Resources TYPO3 Rector: https://github.com/sabbelasichon/typo3-rector Upgrade Guide: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Upgrading/Index.html v13 Changelog: https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog-13/Index.html v14 Changelog: https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog-14/Index.html Credits & Attribution This skill is based on the excellent TYPO3 best practices and methodology developed by Netresearch DTT GmbH. We are deeply grateful for their outstanding contributions to the TYPO3 community and their commitment to sharing knowledge. Netresearch has been a leading force in TYPO3 development, and their expertise has been invaluable in shaping these guidelines. Thank you, Netresearch, for your exceptional work! Copyright (c) Netresearch DTT GmbH - Methodology and best practices Adapted by webconsulting.at for this skill collection ?>