Agent-Skills.md

Agent Skills: TYPO3 Extension Upgrade Skill

>-

UncategorizedID: dirnbauer/webconsulting-skills/typo3-extension-upgrade

Repository

dirnbauer/webconsulting-skills
dirnbauerLicense: NOASSERTION
192

Install this agent skill to your local

pnpm dlx add-skill https://github.com/dirnbauer/webconsulting-skills/tree/HEAD/skills/typo3-extension-upgrade

Skill Files

Browse the full folder contents for typo3-extension-upgrade.

Download Skill

Loading file tree…

skills/typo3-extension-upgrade/SKILL.md

Skill Metadata

Name
"typo3-extension-upgrade"
Description
"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."

TYPO3 Extension Upgrade Skill

Systematic framework for upgrading TYPO3 extensions to newer LTS versions. Extension code only -- NOT for 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

  1. Complete planning phase (consult references/pre-upgrade.md)
  2. Create feature branch (verify git is clean)
  3. Update composer.json constraints for target version
  4. Audit third-party dependencies for major version changes (consult references/third-party-dependency-upgrades.md)
  5. Run rector process --dry-run then review and apply
  6. Run fractor process --dry-run then review and apply
  7. Run php-cs-fixer fix
  8. Run phpstan analyse against each supported dependency version and fix errors
  9. Run phpunit and fix tests
  10. Test in target TYPO3 version(s)
  11. Verify success criteria (consult references/verification.md)

When NOT to Apply Automatically

Do NOT blindly apply Rector/Fractor if dual-version compatibility is needed, tests are missing, changes are unclear, or complex APIs (DBAL, Extbase) are affected. Instead: apply specific rules manually, test between each change.

Third-Party Dependency Upgrades

When composer.json widens constraints to a new major version: enumerate API usages, cross-reference the new version's API, flag interface/concrete-only methods, verify mocks against all supported versions, use adapter pattern for signature differences, run PHPStan against each 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 | Starting an upgrade: planning checklist, version audit, risk assessment | | references/api-changes.md | Checking deprecated/removed APIs by TYPO3 version | | 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 | Maintaining dual compatibility (v12 + v13) | | references/real-world-patterns.md | Looking for real-world migration examples | | references/toolchain-output.md | Understanding Rector/Fractor dry-run output | | references/troubleshooting.md | Rector broke code, PHPStan errors, test failures | | references/third-party-dependency-upgrades.md | Upgrading non-TYPO3 dependencies (major version bumps, adapter patterns) | | references/verification.md | Checking success criteria and real-world testing | | references/multi-version-worktrees.md | Per-LTS worktree layout, backport workflow, cross-version CI matrix |

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