TYPO3 Extension Upgrade Skill
Framework for upgrading TYPO3 extensions to newer LTS versions.
Extension code only, not project/core upgrades.
Upgrade Toolkit
| Tool |
Purpose |
Files |
| Extension Scanner |
Diagnose deprecated APIs |
TYPO3 Backend |
| Rector |
Automated PHP migrations |
.php |
| Fractor |
Non-PHP migrations |
FlexForms, TypoScript, YAML, Fluid |
| PHPStan |
Static analysis |
.php |
Core Workflow
- Complete planning phase (consult
references/pre-upgrade.md)
- Create feature branch (verify git is clean)
- Update
composer.json constraints for target version
- Audit third-party dependencies for major version changes (consult
references/third-party-dependency-upgrades.md)
- Run
rector process --dry-run then review and apply
- Run
fractor process --dry-run then review and apply
- Run
php-cs-fixer fix
- Run
phpstan analyse against each supported dependency version and fix errors
- Run
phpunit and fix tests
- Test in target TYPO3 version(s)
- Verify success criteria (consult
references/verification.md)
When NOT to Apply Automatically
Do NOT blindly apply Rector/Fractor when dual-version compatibility, missing
tests, unclear changes, or complex APIs (DBAL, Extbase) are involved. Instead
apply rules manually, testing between changes.
Third-Party Dependency Upgrades
When composer.json widens a dependency to a new major version: enumerate API usages, cross-reference the new API, verify mocks, use adapter pattern for signature differences, run PHPStan per major version. See references/third-party-dependency-upgrades.md.
Quick Commands
rector process --dry-run && rector process # PHP migrations
fractor process --dry-run && fractor process # Non-PHP migrations
php-cs-fixer fix && phpstan analyse && phpunit # Quality checks
Asset Templates
Config templates in assets/: rector.php, fractor.php, phpstan.neon, phpunit.xml, .php-cs-fixer.php
References
| Reference |
Use when... |
references/pre-upgrade.md |
Planning checklist, version audit, risk assessment |
references/api-changes.md |
Checking deprecated/removed APIs by TYPO3 version |
references/api-traps.md |
Cross-version footguns: TCA restrictions, boot order, DI bypass |
references/upgrade-v11-to-v12.md |
Upgrading from TYPO3 v11 to v12 |
references/upgrade-v12-to-v13.md |
Upgrading from TYPO3 v12 to v13 |
references/upgrade-v13-to-v14.md |
Upgrading from TYPO3 v13 to v14 |
references/dual-compatibility.md |
Dual compatibility (v12 + v13) |
references/real-world-patterns.md |
Real-world migration examples |
references/toolchain-output.md |
Rector/Fractor dry-run output |
references/troubleshooting.md |
Rector broke code, PHPStan errors, test failures |
references/third-party-dependency-upgrades.md |
Non-TYPO3 dependencies (major version bumps, adapter patterns) |
references/verification.md |
Success criteria and real-world testing |
references/multi-version-worktrees.md |
Per-LTS worktree layout, backport workflow, cross-version CI matrix |
references/audit-mode.md |
Assessing/estimating: ticket only non-automatable findings |
scripts/scan-deprecations.sh <path> |
Deterministic grep scan for deprecated/removed APIs and traps |
External Resources
Credits & Attribution
This skill is based on the excellent work by
Netresearch DTT GmbH.
Original repository: https://github.com/netresearch/typo3-extension-upgrade-skill
Copyright (c) Netresearch DTT GmbH — Methodology and best practices (MIT / CC-BY-SA-4.0)
Special thanks to Netresearch DTT GmbH for their generous open-source contributions to the TYPO3 community, which helped shape this skill collection.
Adapted by webconsulting.at for this skill collection
1---2name: typo3-extension-upgrade3description: Use when upgrading TYPO3 extensions to newer LTS versions (v11->v12, v12->v13, v13->v14 - v14.3 LTS is the current target), running Extension Scanner, Rector, Fractor, PHPStan, fixing deprecated APIs, or resolving compatibility issues. Also triggers on: migration, version upgrade, deprecated API, dual-version compatibility, Fluid 5 strict VHs, HashService removal, ext_tables.php split.4---56# TYPO3 Extension Upgrade Skill78Framework for upgrading TYPO3 extensions to newer LTS versions.9Extension code only, not project/core upgrades.1011## Upgrade Toolkit1213| Tool | Purpose | Files |14|------|---------|-------|15| Extension Scanner | Diagnose deprecated APIs | TYPO3 Backend |16| Rector | Automated PHP migrations | `.php` |17| Fractor | Non-PHP migrations | FlexForms, TypoScript, YAML, Fluid |18| PHPStan | Static analysis | `.php` |1920## Core Workflow21221. Complete planning phase (consult `references/pre-upgrade.md`)232. Create feature branch (verify git is clean)243. Update `composer.json` constraints for target version254. **Audit third-party dependencies** for major version changes (consult `references/third-party-dependency-upgrades.md`)265. Run `rector process --dry-run` then review and apply276. Run `fractor process --dry-run` then review and apply287. Run `php-cs-fixer fix`298. Run `phpstan analyse` **against each supported dependency version** and fix errors309. Run `phpunit` and fix tests3110. Test in target TYPO3 version(s)3211. Verify success criteria (consult `references/verification.md`)3334## When NOT to Apply Automatically3536Do NOT blindly apply Rector/Fractor when dual-version compatibility, missing37tests, unclear changes, or complex APIs (DBAL, Extbase) are involved. Instead38apply rules manually, testing between changes.3940## Third-Party Dependency Upgrades4142When `composer.json` widens a dependency to a new major version: enumerate API usages, cross-reference the new API, verify mocks, use adapter pattern for signature differences, run PHPStan per major version. See `references/third-party-dependency-upgrades.md`.4344## Quick Commands4546```bash47rector process --dry-run && rector process # PHP migrations48fractor process --dry-run && fractor process # Non-PHP migrations49php-cs-fixer fix && phpstan analyse && phpunit # Quality checks50```5152## Asset Templates5354Config templates in `assets/`: `rector.php`, `fractor.php`, `phpstan.neon`, `phpunit.xml`, `.php-cs-fixer.php`5556## References5758| Reference | Use when... |59|-----------|-------------|60| `references/pre-upgrade.md` | Planning checklist, version audit, risk assessment |61| `references/api-changes.md` | Checking deprecated/removed APIs by TYPO3 version |62| `references/api-traps.md` | Cross-version footguns: TCA restrictions, boot order, DI bypass |63| `references/upgrade-v11-to-v12.md` | Upgrading from TYPO3 v11 to v12 |64| `references/upgrade-v12-to-v13.md` | Upgrading from TYPO3 v12 to v13 |65| `references/upgrade-v13-to-v14.md` | Upgrading from TYPO3 v13 to v14 |66| `references/dual-compatibility.md` | Dual compatibility (v12 + v13) |67| `references/real-world-patterns.md` | Real-world migration examples |68| `references/toolchain-output.md` | Rector/Fractor dry-run output |69| `references/troubleshooting.md` | Rector broke code, PHPStan errors, test failures |70| `references/third-party-dependency-upgrades.md` | Non-TYPO3 dependencies (major version bumps, adapter patterns) |71| `references/verification.md` | Success criteria and real-world testing |72| `references/multi-version-worktrees.md` | Per-LTS worktree layout, backport workflow, cross-version CI matrix |73| `references/audit-mode.md` | Assessing/estimating: ticket only non-automatable findings |74| `scripts/scan-deprecations.sh <path>` | Deterministic grep scan for deprecated/removed APIs and traps |7576## External Resources7778- [TYPO3 Rector](https://github.com/sabbelasichon/typo3-rector)79- [Fractor](https://github.com/andreaswolf/fractor)80- [TYPO3 Core Changelog](https://docs.typo3.org/c/typo3/cms-core/main/en-us/)8182---8384## Credits & Attribution8586This skill is based on the excellent work by87**[Netresearch DTT GmbH](https://www.netresearch.de/)**.8889Original repository: https://github.com/netresearch/typo3-extension-upgrade-skill9091**Copyright (c) Netresearch DTT GmbH** — Methodology and best practices (MIT / CC-BY-SA-4.0)9293Special thanks to [Netresearch DTT GmbH](https://www.netresearch.de/) for their generous open-source contributions to the TYPO3 community, which helped shape this skill collection.94Adapted by webconsulting.at for this skill collection
dirnbauer