What is typo3-extension-upgrade?

It is a framework-driven process to upgrade TYPO3 extensions to newer LTS versions using an integrated toolkit (Extension Scanner, Rector, Fractor, PHPStan, and tests).

When should I use this skill?

When upgrading extension code across TYPO3 LTS versions (e.g., v11 to v12, v12 to v13, v13 to v14) and you need structured planning, migrations, and thorough testing.

What tools are involved?

Extension Scanner for deprecated APIs, Rector for PHP migrations, Fractor for non-PHP migrations, PHPStan for static analysis, PHP-CS-Fixer, and PHPUnit for tests.

typo3-extension-upgrade

npx machina-cli add skill netresearch/typo3-extension-upgrade-skill/typo3-extension-upgrade --openclaw

Files (1)

SKILL.md

3.7 KB

TYPO3 Extension Upgrade Skill

Systematic framework for upgrading TYPO3 extensions to newer LTS versions.

Scope: Extension code upgrades only. NOT for TYPO3 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
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 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 if:

You need dual-version compatibility (v12 + v13)
The extension has no tests to verify changes
The diff shows changes you don't understand
The rule affects complex APIs (DBAL, Extbase internals)

Instead: apply specific rules manually, test between each change.

Quick Commands

# Rector: automated PHP migrations
./vendor/bin/rector process --dry-run && ./vendor/bin/rector process

# Fractor: non-PHP migrations
./vendor/bin/fractor process --dry-run && ./vendor/bin/fractor process

# Quality checks
./vendor/bin/php-cs-fixer fix && ./vendor/bin/phpstan analyse && ./vendor/bin/phpunit

TYPO3 Changelogs

Version	Changelog
v14	Changelog-14
v13	Changelog-13
v12	Changelog-12

Asset Templates

Configure tooling by copying and adjusting these templates:

assets/rector.php - Rector configuration for PHP migrations
assets/fractor.php - Fractor configuration for non-PHP migrations
assets/phpstan.neon - PHPStan static analysis configuration
assets/phpunit.xml - PHPUnit test configuration
assets/.php-cs-fixer.php - PHP-CS-Fixer code style configuration

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/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/verification.md`	Checking success criteria and real-world testing

External Resources

Contributing: https://github.com/netresearch/typo3-extension-upgrade-skill

Source

git clone https://github.com/netresearch/typo3-extension-upgrade-skill/blob/main/skills/typo3-extension-upgrade/SKILL.mdView on GitHub

Overview

TYPO3 Extension Upgrade is a systematic framework for upgrading TYPO3 extensions to newer LTS versions (v11 to v12, v12 to v13, v13 to v14). It focuses on extension code upgrades only, not TYPO3 project/core upgrades, and guides you through planning, tool-assisted migrations, static analysis, and thorough testing using Extension Scanner, Rector, Fractor, PHPStan, and PHPUnit.

How This Skill Works

It follows a repeatable workflow: plan and create a feature branch, update composer.json constraints for the target version, perform dry-run migrations with Rector and Fractor and then apply, run php-cs-fixer, analyze with PHPStan, run PHPUnit tests, and test in the target TYPO3 versions to verify success criteria.

When to Use It

Upgrading an extension from TYPO3 v11 to v12
Upgrading an extension from TYPO3 v12 to v13
Upgrading an extension from TYPO3 v13 to v14
Maintaining dual compatibility for v12 and v13 during an upgrade
Setting up a repeatable upgrade workflow with planning and verification

Quick Start

Step 1: Plan the upgrade, create a feature branch, and audit with references/pre-upgrade.md
Step 2: Run rector dry-run, review changes, then run fractor dry-run and apply, update composer.json as needed
Step 3: Run php-cs-fixer fix, then phpstan analyse and phpunit; test in target TYPO3 versions and verify success criteria

Best Practices

Plan the upgrade by consulting references/pre-upgrade.md and create a feature branch with a clean git state
Use Extension Scanner to diagnose deprecated APIs before making changes
Run Rector for PHP migrations and Fractor for non-PHP migrations, starting with dry-runs
Run PHPStan and PHPUnit after applying changes and fix any issues
Test the extension in the target TYPO3 version(s) and verify success criteria using references/verification.md

Example Use Cases

Upgrade a v11 extension to v12 while preserving dual compatibility for v12 and v13
Migrate non-PHP assets like TypoScript, YAML, and FlexForms with Fractor
Apply Rector migrations for PHP code and resolve PHPStan errors surfaced during analysis
Run end-to-end tests with PHPUnit and validate behavior in TYPO3 v13
Consult real-world patterns and troubleshooting guidance during complex upgrades

Frequently Asked Questions

Add this skill to your agents