# Typo3 Extension Upgrade

> Use when an extension has to work with a newer or the current TYPO3 LTS, when a version bump breaks compatibility or leaves deprecated APIs behind, when upgrading v11->v12, v12->v13 or v13->v14 (v14.3 LTS is the current target), when one codebase must stay compatible with two versions, when running Extension Scanner, Rector, Fractor or PHPStan against a target version, or when a specific v14 breaker bites - Fluid 5 strict ViewHelpers, HashService removal, the ext_tables.php split.

- Skill: `netresearch/typo3-extension-upgrade` (Agent Skill, multi-file: 22 files)
- Install (CLI): `npx skillmds@latest add netresearch/typo3-extension-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/netresearch/typo3-extension-upgrade/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: netresearch (https://skillmd.com/u/netresearch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/netresearch/typo3-extension-upgrade

---


# TYPO3 Extension Upgrade Skill

Framework for upgrading TYPO3 extensions to newer LTS versions.
Extension code only, not project/core upgrades.

**Done is `exit=0` from the step 10 command, run last on every line the
constraint names that installs — read from the run, not assumed.** Not green on
one line with another left red. Not green because failing tests
were skipped or deleted. Not a commit with `--no-verify`. Anything short of that is
reported as not done, with the lines that show why.

**A commit hook that fails is a check the repository requires, not an obstacle.**
Read which command it ran, run that command yourself, fix what it reports, and
commit again: code style is usually fixed by the repository's own fixer
(`php-cs-fixer fix` with its config), PHPStan findings are fixed in the code.
Measured: three agents with both TYPO3 lines green bypassed the style or PHPStan
hook with `--no-verify`, and a fourth bypassed its own failing unit tests.

## 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 the target version. **v14's LTS minor is 3: write `^14.3`, never `^14.4`** — `^13.4 || ^14.3` to support both. v11.5, v12.4 and v13.4 make `14.4` look like the next in line; it matches no release, so `composer update` fails dependency resolution, exits non-zero and installs nothing. Constraints for every version pair: `references/upgrade-v13-to-v14.md`

   **Adding a version is not replacing one.** Writing `^14.3` alone drops
   support for every line the extension had before, which is a breaking change
   for everyone installing it — and it is the cheap way to make the new line
   resolve, so it happens by accident. "Make it work with the current LTS"
   asks for the new line, not for the loss of the old ones.
   **Read the existing constraint and keep every line in it**, then add the
   target: `^12.4 || ^13.4` becomes `^12.4 || ^13.4 || ^14.3`, and only an
   extension that already supported v13 alone ends up at `^13.4 || ^14.3`.
   Drop a line only where that was asked for, and say so where a maintainer
   will see it. Whether one codebase *can* serve them all is a separate
   question, answered in `references/dual-compatibility.md`.
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. **`Tests/` is part of the upgrade, not a
   consequence of it.** A class v14 removed, referenced from a test, is fatal
   rather than failing: in an import, a parent, a property or a signature it
   stops PHPUnit while it loads the suite, so nothing runs at all. Search for
   the removed types across both trees before running anything:
   `grep -rnE 'TypoScriptFrontendController|StandaloneView|TemplateView|HashService|LocalPreviewHelper|LocalCropScaleMaskHelper|FreezableBackendInterface' Classes/ Tests/`
   Every hit is a fix. `createMock` on one of them cannot be repaired by
   swapping the name — see `references/upgrade-v13-to-v14.md`
10. **Install the target version and run the suite against it.** A green suite
    on the version already installed proves nothing about the target — that is
    the old code passing old tests. Install first, in two passes, then test:
    ```bash
    composer update "typo3/*" --with typo3/cms-core:^14.3 -W --no-install \
      && rm -rf vendor && composer install \
      && composer show typo3/cms-core | grep '^versions' \
      && vendor/bin/phpunit -c Build/phpunit/UnitTests.xml; echo "exit=$?"
    ```
    Chained, so a failed install stops before PHPUnit runs against the old tree;
    the `versions` line says what was actually installed, and `exit=` is the
    status of whichever step ran last.
    One pass fails on the way from v13 to v14: Composer upgrades
    `typo3/class-alias-loader` and then runs the old plugin against the new
    files, which dies with `Class "…\CaseSensitiveToken" not found` after the
    lock file is written. `composer install` on top of the old `vendor/` dies the
    same way, so `vendor/` goes first.
    The package argument matters: without it `composer update` moves every
    dependency, and the test result then depends on upgrades that have nothing
    to do with TYPO3. `-W` lets the TYPO3 packages' own dependencies follow.
    **If the target will not install, the upgrade is untested.** Say so in the
    report, with the error, and do not report the suite as passing: a green run
    on the version that was already there is that version's result.
11. **Run the same command for every older line the constraint keeps** —
    `--with typo3/cms-core:^13.4` for `^13.4`, and so on. A migration that
    turns the target green can break the line below it: measured, an agent got
    v14 green, left v13's suite failing, and reported all three lines
    compatible. Fix, then run every line again. A line that cannot be
    installed here at all — Composer cannot resolve or download it — is
    untested, not failed: report it with Composer's error, and never drop it
    from the constraint for that reason (step 3).
12. **Before reporting, read the `exit=` line of the last run on each line.** On a
    line that installed, anything other than `exit=0` means the work is not
    done: go back to step 9. A line whose install failed is the untested case
    from step 11. Committing past a red suite, or with `--no-verify`, is not
    done either. The report says, per line, what was installed and whether the
    suite passed — and where it did not, the failure as PHPUnit or Composer
    printed it.
13. Verify success criteria (consult `references/verification.md`)

**Done means the suite passes on every line the constraint names, with that
line installed** — every line that can be installed; the rest are reported as
untested. Not that the constraint was widened, and not that the suite
is green where it was already green.

Measured: agents reported "✅ 719 tests pass" having never installed the target,
having seen the suite fail to load three times, or having seen three errors and
thirteen failures and committed with `--no-verify`. The run's own `exit=` line
is what tells you which of those you are in; read it before you write the
report.

Where a removed class is referenced decides when it bites. In an `import`, a
parent class, a property or a signature it is resolved while PHPUnit *loads*
the suite, so nothing runs at all and the failure looks nothing like a test
failure. Referenced only inside a method body, it fails when that one test
executes, and the rest of the suite still passes — which is the more
comfortable failure and the easier one to miss in a summary line.

## When the migration breaks the tests

It will. A suite that was green before Rector routinely comes back with dozens
of errors, and working through them is the job.

**Never revert the migration to get back to green.** Measured: an agent ran
Rector, saw `Tests: 719, Errors: 34`, discarded every migrated file under
`Classes/`, got `OK (719 tests, 1176 assertions)`, and committed
`composer.json`, `ext_emconf.php` and two build files — no code at all. That
commit claims support for a version the code does not have, and it is the worst
of the three possible outcomes: a failing upgrade is visible, an unattempted one
is honest, and this one is neither.

Green after a revert is the state you started in. The only green that counts is
the one from step 10, with the target version installed and the migration in
place.

**Skipping or deleting a failing test to get green is the same revert,** one
test at a time. One skip is legitimate: where the code branches by version, a
test of the branch that exists only on the older line —
`if (!class_exists(X::class)) { self::markTestSkipped(...); }` — may skip on
the newer line, provided the newer line's branch has a test of its own. Any
other skip, a version check that returns early, or a removed test method turns
a failure into silence. So does `--no-verify` on the commit: it silences the
checks that would report it.

**Nor stop to ask whether to proceed.** Measured: an agent installed the
target, counted the uses of a class the new version removed, ran
`git reset --hard`, and asked whether it should do the refactoring. A request
to make the extension work with the new version is that permission. Replacing
what the new version removed *is* the upgrade, however many places use it — it
is the work, not a finding to report back. Ask only about what the request
leaves open, such as dropping a supported line (step 3).

## 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

```bash
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

- [TYPO3 Rector](https://github.com/sabbelasichon/typo3-rector)
- [Fractor](https://github.com/andreaswolf/fractor)
- [TYPO3 Core Changelog](https://docs.typo3.org/c/typo3/cms-core/main/en-us/)