Automate TYPO3 Upgrades with TYPO3 Rector: Complete 2026 Migration Guide

TYPO3 upgrades once meant days of manual refactoring, deprecated API fixes, and changelog reviews. In 2026, that approach no longer scales.

With TYPO3 v14 LTS released in April 2026 and TYPO3 v12 free support ended, many agencies and developers are modernizing legacy TYPO3 projects faster than ever. Manual upgrades are slow, error-prone, and difficult to maintain.

TYPO3 Rector automates much of the migration process. Built on top of Rector, it reads official TYPO3 changelogs and automatically refactors deprecated code, updates TCA configurations, modernizes APIs, and prepares extensions for newer TYPO3 versions.

Instead of spending days on repetitive fixes, you can focus on testing and validation.

In this guide, you’ll learn how to install, configure, and use TYPO3 Rector for faster and safer TYPO3 upgrades in 2026.

What is a TYPO3 Rector?

TYPO3 Rector is an automated refactoring tool for TYPO3 upgrades. It helps developers migrate TYPO3 websites and extensions between versions with fewer manual changes.

TYPO3 Rector analyzes your codebase and automatically applies upgrade rules based on official TYPO3 changelogs and deprecations.

It can automate:

• Deprecated API replacements
• PHP and TCA refactoring
• Namespace and class updates
• Method signature changes
• Event migration preparation
• Configuration modernization

TYPO3 Rector works alongside other TYPO3 upgrade tools:

• TYPO3 Rector → automated PHP/TCA refactoring
• Extension Scanner → detects deprecated TYPO3 APIs
• Upgrade Wizards → handle database and system upgrades

By automating repetitive migration work, TYPO3 Rector helps keep TYPO3 v10, v11, v12, v13, and v14 projects upgrade-ready with significantly less effort.

TYPO3 Rector in 2026: What It Automates vs What It Cannot

Manual TYPO3 upgrades are slow and error-prone. Developers often spend hours reviewing changelogs, fixing deprecated APIs, and updating legacy extensions manually.

TYPO3 Rector automates much of this repetitive work using official TYPO3 migration rules, reducing upgrade time from days to hours.

What TYPO3 Rector Automates

TYPO3 Rector can automatically handle:

• Deprecated TYPO3 API migrations
• PHP namespace and class refactoring
• TCA normalization
• Method signature updates
• Event and hook migration preparation
• TYPO3 configuration modernization
• Extension code refactoring

Benefits include:

• Faster TYPO3 upgrades
• Fewer missed deprecations
• Consistent refactoring
• Reduced manual work
• More time for testing and QA

What TYPO3 Rector Cannot Automate

TYPO3 Rector still requires manual validation for:

• Business logic testing
• Fluid and frontend redesigns
• Third-party extension compatibility
• Database cleanup decisions
• QA and functional testing
• Project-specific edge cases

TYPO3 Rector should be treated as an upgrade automation assistant, not a replacement for testing and release validation.

TYPO3 Rector vs Manual TYPO3 Upgrades

Traditional TYPO3 upgrades involve manual refactoring, deprecated API fixes, and repetitive code updates. As TYPO3 projects grow larger, manual migrations become slower and harder to maintain.

TYPO3 Rector automates many of these tasks using official TYPO3 migration rules.

For many TYPO3 agencies and development teams in 2026, TYPO3 Rector has become a core tool for reducing upgrade effort and maintaining TYPO3 v12, v13, and v14 compatibility.

TYPO3 Rector vs Extension Scanner vs Fractor

Modern TYPO3 upgrades often combine multiple tools, each handling a different part of the migration workflow.

TYPO3 Rector

Automates TYPO3-specific PHP and TCA refactoring using official TYPO3 migration rules.

TYPO3 Extension Scanner

Detects deprecated APIs and extension compatibility issues but does not rewrite code automatically.

TYPO3 Upgrade Wizard

Handles database schema updates and system-level migrations after TYPO3 core upgrades.

Fractor

Complements TYPO3 Rector by modernizing:

• TypoScript
• FlexForms
• XML
• YAML
• composer.json files

Many TYPO3 agencies now combine TYPO3 Rector, Fractor, Extension Scanner, and Upgrade Wizards for safer upgrade workflows.

TYPO3 Version & PHP Compatibility Matrix (2026)

Before running TYPO3 Rector, verify TYPO3 and PHP compatibility to avoid migration conflicts.

As of May 2026:

• TYPO3 14.3.1 is the current stable release
• TYPO3 v14 LTS launched on April 21, 2026

• TYPO3 v12 free support ended on April 30, 2026

TYPO3 v14 Support Timeline

TYPO3 v14 LTS includes:

• Bug fix support until December 2027
• Security support until June 2029

For most TYPO3 projects in 2026, TYPO3 v14 with PHP 8.2+ is the recommended long-term upgrade target.

TYPO3 Upgrade Readiness Checklist

Before using TYPO3 Rector, make sure your TYPO3 project is properly prepared.

Pre-Upgrade Checklist

• Composer-based TYPO3 setup
• TYPO3 and PHP versions documented
• Compatible PHP version for target TYPO3 release
• Database and project backups completed
• Git version control enabled
• Clean staging or local environment ready
• TYPO3 extensions audited
• Unsupported extensions identified
• TYPO3 Extension Scanner executed
• Critical workflows documented
• CI/CD validation prepared

Important Safety Recommendations

Never run TYPO3 Rector on production systems. Always perform migrations in local or staging environments where changes can be reviewed, tested, and rolled back safely.

Create a Git commit before every major migration step to simplify rollback and debugging.

Recommended TYPO3 Upgrade Workflow (2026)

A safe TYPO3 upgrade workflow combines automated refactoring, compatibility checks, and testing.

1. Audit TYPO3 & PHP Versions

Review:

• Current TYPO3 version
• PHP version
• Installed extensions
• Composer dependencies

2. Upgrade PHP First

Newer TYPO3 versions often require modern PHP versions:

• TYPO3 v12 → PHP 8.1+
• TYPO3 v14 → PHP 8.2+

3. Run TYPO3 Extension Scanner

Detect:

• Deprecated TYPO3 APIs
• Legacy extension issues
• Removed core methods

4. Install TYPO3 Rector

Install TYPO3 Rector using Composer globally or per project.

5. Create Backups & Git Commit

git add .

git commit -m “Backup before TYPO3 Rector migration”

6. Run Dry-Run Mode

vendor/bin/typo3-rector process --dry-run

Review API replacements, TCA updates, and namespace changes before applying migrations.

7. Apply TYPO3 Rector Changes

vendor/bin/typo3-rector process

Upgrade incrementally:

• TYPO3 v10 → v11
• TYPO3 v11 → v12
• TYPO3 v12 → v13
• TYPO3 v13 → v14

8. Run Fractor

Use Fractor for TypoScript, XML, and FlexForm migrations.

9. Execute Database Upgrades

After migration:

• Run Upgrade Wizards
• Apply database schema updates
• Clear caches

10. Perform QA & Testing

Validate:

• Backend workflows
• Frontend rendering
• Extensions
• Scheduler tasks
• Forms and APIs

11. Deploy Safely

Deploy gradually, monitor logs, and keep rollback plans ready during production releases.

Installing TYPO3 Rector

TYPO3 Rector can be installed globally, per project, or as a standalone PHAR file. For most TYPO3 projects in 2026, Composer-based installation is the recommended approach.

Global Installation

Useful for developers or TYPO3 agencies managing multiple projects.

Install globally:

composer global require ssch/typo3-rector

Add Composer’s global bin directory to PATH:

export PATH="$PATH:$HOME/.composer/vendor/bin"

Verify installation:

typo3-rector --version

Project Installation

Recommended for:

• Team projects
• CI/CD pipelines
• Version-controlled environments

Install locally:

composer require --dev ssch/typo3-rector

Run TYPO3 Rector:

vendor/bin/typo3-rector process

PHAR Installation

Useful for quick testing or isolated environments.

Download PHAR:

wget https:// github.com/sabbelasichon/typo3-rector/releases/latest/download/typo3-rector.phar

Make executable:

chmod +x typo3-rector.phar

Run TYPO3 Rector:

./typo3-rector.phar process

Which Installation Method Should You Choose?

Recommended Approach for 2026

For most modern TYPO3 projects, project-level Composer installation is the safest option because:

• TYPO3 Rector versions stay consistent
• CI/CD workflows remain reproducible
• Teams share the same migration setup
• Dependencies stay version-controlled

Global installation is still useful for agencies managing multiple TYPO3 projects.

Creating Your First rector.php Configuration

After installing TYPO3 Rector, create a rector.php configuration file. It defines:

• Which TYPO3 directories to scan
• Which migration rules to run
• Which files or folders to skip

A good configuration helps reduce upgrade risks and unnecessary code changes.

Recommended Starter Configuration for 2026

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Ssch\TYPO3Rector\Set\Typo3SetList;

return RectorConfig::configure()
   ->withPaths([
       __DIR__ . '/packages',
       __DIR__ . '/typo3conf/ext',
   ])
   ->withSets([
       Typo3SetList::TYPO3_12,
       Typo3SetList::TYPO3_13,
   ])
   ->withSkip([
       __DIR__ . '/vendor',
       '*/Resources/Public/*',
       '*/node_modules/*',
   ]);

Understanding the Main Configuration Options

Paths

Defines which TYPO3 directories Rector should process:

->withPaths([
   __DIR__ . '/packages',
   __DIR__ . '/typo3conf/ext',
   __DIR__ . '/src',
])

Common paths:

• TYPO3 extensions
• Site packages
• PHP source directories

TYPO3 Rector Sets

Defines which TYPO3 migration rules should run:

->withSets([
   Typo3SetList::TYPO3_12,
   Typo3SetList::TYPO3_13,
])

Each set contains version-specific TYPO3 upgrade rules.

Skip Rules

Excludes directories or files from processing:

->withSkip([
   __DIR__ . '/vendor',
   '*/Resources/Public/*',
   '*/Tests/*',
])

Useful for excluding:

• Vendor code
• Generated assets
• Frontend libraries
• Test directories

Safer TYPO3 Rector Configuration Tips

For safer TYPO3 upgrades:

• Apply one TYPO3 set at a time
• Process custom extensions first
• Exclude vendor/public assets
• Start with --dry-run
• Commit after every migration step

Common rector.php Configuration Mistakes

Running Too Many TYPO3 Sets at Once

Applying multiple major TYPO3 migration sets together can make debugging difficult.

Processing Vendor Directories

Never run Rector inside:

• /vendor
• node_modules
• generated frontend assets

Skipping Dry Runs

Always review changes before applying them.

Running on Production

TYPO3 Rector should only run in:

• Local development environments
• Staging servers
• CI/CD validation pipelines

Never execute automated TYPO3 migrations directly on production systems.

Understanding TYPO3 Rector Sets

TYPO3 Rector uses predefined “sets” for specific TYPO3 versions. Each set contains automated migration rules based on TYPO3 deprecations and API changes.

Common TYPO3 Rector Sets

Example:

->withSets([
   Typo3SetList::TYPO3_12,
])

TCA Migration Sets

TYPO3 Rector also includes dedicated TCA migration sets:

->withSets([
   Typo3SetList::TCA_120,
])

TCA rules help:

• Normalize TCA arrays
• Convert legacy item formats
• Modernize backend configurations

For large TYPO3 projects, running TCA migrations separately is usually safer.

Avoid Combining Multiple TYPO3 Sets

Running several major TYPO3 sets together can:

• Increase false positives
• Create overlapping changes
• Break legacy extensions
• Make debugging harder

Avoid setups like:

->withSets([
   Typo3SetList::TYPO3_95,
   Typo3SetList::TYPO3_14,
])

Instead, apply Rector sets incrementally and validate after each step.

Recommended Incremental TYPO3 Upgrade Strategy

Safest upgrade path for 2026:

1. TYPO3 v9 → v10
2. TYPO3 v10 → v11
3. TYPO3 v11 → v12
4. TYPO3 v12 → v13
5. TYPO3 v13 → v14

Recommended workflow:

• Apply one Rector set
• Run tests
• Fix issues
• Commit changes
• Continue to next version

This reduces migration risk and simplifies rollback.

Why Incremental TYPO3 Upgrades Matter

Skipping TYPO3 versions can cause:

• Broken extension APIs
• Missing deprecation fixes
• PHP compatibility conflicts
• Invalid TCA configurations
• Difficult debugging

Older TYPO3 extensions often rely on deprecated hooks, outdated APIs, and legacy database logic. Incremental upgrades make it easier to:

• Detect issues earlier
• Maintain extension compatibility
• Validate changes step-by-step
• Reduce deployment risk

For most TYPO3 projects in 2026, staged upgrades remain the safest migration strategy.

Running TYPO3 Rector Safely

TYPO3 Rector can automate large parts of TYPO3 upgrades, but safe migration practices are still essential.

Dry Runs

Preview changes before modifying files:

vendor/bin/typo3-rector process --dry-run

Dry runs help detect risky refactors and deprecated API replacements before applying migrations.

Git Workflow

Always create a Git backup before running TYPO3 Rector:

git add .


git commit -m "Backup before TYPO3 Rector migration"

After migration:

git diff

Best practices:

• Apply one Rector set at a time
• Review changes carefully
• Commit after each migration step

Rollback Strategy

Always keep:

• Git backups
• Database backups
• Staging environments
• Rollback plans

If issues appear, revert changes quickly using Git or deployment workflows.

Never Run Rector on Production

Never execute TYPO3 Rector directly on production systems.

Run migrations only in:

• Local development
• Staging environments
• CI/CD pipelines

Always test TYPO3 upgrades before deployment.

Migrating Custom TYPO3 Extensions

TYPO3 Rector is especially useful for upgrading custom TYPO3 extensions.

Example configuration:

return RectorConfig::configure()
   ->withPaths([
       __DIR__ . '/Classes',
       __DIR__ . '/Configuration',
   ])
   ->withSets([
       Typo3SetList::TYPO3_12,
       Typo3SetList::TYPO3_13,
       Typo3SetList::TYPO3_14,
   ])
   ->withSkip([
       __DIR__ . '/Resources',
   ]);

TYPO3 Rector can modernize:

• Deprecated TYPO3 APIs
• Legacy namespaces
• TCA configurations
• Old hook implementations
• Event migration preparation

For TYPO3 v12–v14 upgrades, extensions may also require:

• PSR-14 event migration
• Composer updates
• PHP 8.2+ compatibility fixes

Always test custom extensions separately after migration, especially when legacy TYPO3 integrations are involved.

Handling Third-Party Extensions During TYPO3 Upgrades

Third-party extensions are one of the biggest risks during TYPO3 upgrades.

Common issues:

• Composer conflicts
• Unsupported TYPO3 versions
• Abandoned extensions
• Deprecated APIs
• Missing PHP 8.2+ support

Before upgrading:

• Audit installed extensions
• Check TYPO3/PHP compatibility
• Review Composer and TER constraints

Common strategies:

• Replace outdated extensions
• Fork abandoned packages
• Apply Composer patches
• Run TYPO3 Rector on custom forks

Sometimes replacing a legacy extension is safer than maintaining unsupported code.

TYPO3 v14 Migration Considerations

With TYPO3 v14 LTS released in April 2026, projects should prepare for:

• PHP 8.2+ compatibility
• Removed TYPO3 APIs
• PSR-14 event migrations
• Backend modernization
• Extension compatibility updates

TYPO3 v14 continues TYPO3’s move toward modern PHP standards, dependency injection, and cleaner APIs.

Older TYPO3 extensions may still require manual refactoring and testing.

Real TYPO3 Migration Examples

Signal/Slot → PSR-14

Before:

$dispatcher->connect(...);

After:

services:
 MyEventListener:
   tags:
     - name: event.listener

TCA Migration

Before:

['Label', 123, 'icon.svg']

After:

[
 'label' => 'Label',
 'value' => 123,
 'icon' => 'icon.svg'
]

Database API Migration

Before:

$GLOBALS['TYPO3_DB']->exec_SELECTquery(...);

After:

GeneralUtility::makeInstance(ConnectionPool::class)

Advanced TYPO3 Rector Configuration

For large or complex TYPO3 projects, TYPO3 Rector supports advanced configuration options for better performance, custom migrations, and faster processing.

Custom Rules

You can add custom Rector rules for project-specific TYPO3 migrations:

return RectorConfig::configure()

    ->withRules([
       MyCustomRector::class,
   ]);

Custom rules are useful for:

• Legacy internal APIs
• Company-specific coding standards
• Repeated manual refactoring tasks

Parallel Processing

Enable parallel execution to speed up large TYPO3 migrations:

return RectorConfig::configure()

    ->withParallel()
   ->withPaths([
       __DIR__ . '/packages',
   ]);

This is especially useful for enterprise TYPO3 projects with many extensions.

Memory Limits

Large TYPO3 codebases may require higher PHP memory limits:

return RectorConfig::configure()
   ->withMemoryLimit('2G');

Or via CLI:

php -d memory_limit=2G vendor/bin/typo3-rector process

Selective Processing

Process only changed PHP files for faster CI/CD workflows:

CHANGED_FILES=$(git diff --name-only --diff-filter=AM main...HEAD | grep '\.php$')

vendor/bin/typo3-rector process $CHANGED_FILES

Selective processing helps reduce execution time during pull requests and automated TYPO3 upgrade checks.

TYPO3 Rector for Enterprise & Large Legacy Projects

Large TYPO3 projects often include monorepos, multisite setups, and large extension ecosystems. During enterprise TYPO3 upgrades, performance optimization becomes important.

Recommended practices:

• Enable parallel processing
• Increase PHP memory limits
• Process extensions incrementally
• Exclude vendor and public asset folders
• Use CI chunking for large repositories

Example:

return RectorConfig::configure()
   ->withParallel(8)
   ->withMemoryLimit('4G');

Common TYPO3 Rector Errors and Fixes

Out of Memory Errors

php -d memory_limit=2G vendor/bin/typo3-rector process

Composer Conflicts

• Update Composer dependencies
• Verify TYPO3 extension compatibility
• Check PHP version support

Missing Class Errors

Usually caused by outdated extensions or broken autoloading.

Fix with:

composer dump-autoload

Debug Mode

vendor/bin/typo3-rector process --debug

Xdebug Support

php -d xdebug.mode=debug vendor/bin/typo3-rector process

Testing Strategy After TYPO3 Migration

After running TYPO3 Rector, always test your TYPO3 project carefully.

Recommended checks:

• Backend smoke testing
• Frontend rendering validation
• Editor workflow testing
• Scheduler task verification
• Extension integration tests
• PHPUnit and CI/CD pipelines

TYPO3 Rector automates migrations, but manual QA and functional testing are still essential.

Integrating TYPO3 Rector into CI/CD

Integrating TYPO3 Rector into CI/CD pipelines helps teams detect deprecated TYPO3 code early and maintain upgrade-ready TYPO3 projects.

GitHub Actions

name: TYPO3 Rector Check

on: [push, pull_request]

jobs:
 rector:
   runs-on: ubuntu-latest

   steps:
     - uses: actions/checkout@v3

     - name: Setup PHP
       uses: shivammathur/setup-php@v2
       with:
         php-version: 8.2

     - name: Install dependencies
       run: composer install

     - name: Run TYPO3 Rector
       run: vendor/bin/typo3-rector process --dry-run

GitLab CI

rector:
 image: php:8.2

 script:
   - composer install
   - vendor/bin/typo3-rector process --dry-run

PHPStan & Static Analysis Integration

Many TYPO3 teams combine TYPO3 Rector with:

• PHPStan
• TYPO3 Extension Scanner
• PHPUnit

This helps detect:

• Type errors
• Deprecated TYPO3 APIs
• Broken extension logic
• Migration regressions

Automated Pull Request Validation

Running TYPO3 Rector checks on pull requests helps:

• Catch deprecated code early
• Keep TYPO3 projects upgrade-ready
• Prevent legacy APIs from entering the codebase
• Maintain consistent coding standards across teams

For enterprise TYPO3 projects, CI/CD validation is now a standard part of long-term upgrade maintenance.

Working with Fractor

Fractor complements TYPO3 Rector by handling non-PHP TYPO3 files such as:

• TypoScript
• FlexForms
• XML
• YAML
• composer.json

Fractor becomes useful when TYPO3 upgrades require TypoScript modernization or configuration refactoring beyond PHP code changes.

Typical workflow:

1. Run TYPO3 Rector for PHP and TCA migrations
2. Run Fractor for TypoScript and XML updates
3. Execute TYPO3 Upgrade Wizards
4. Test the project

For larger TYPO3 upgrades, Rector + Fractor together provide a more complete migration workflow.

Recommended TYPO3 Upgrade Toolchain in 2026

Modern TYPO3 upgrade workflows usually combine multiple tools:

Using these tools together helps reduce upgrade risk and improve long-term TYPO3 maintainability.

Can TYPO3 Rector Upgrade TYPO3 7 Projects?

Yes, but older TYPO3 v7 projects usually require a staged migration approach.

Typical upgrade path:

• TYPO3 v7 → v8
• TYPO3 v8 → v9
• TYPO3 v9 → v10+
• Continue incrementally toward TYPO3 v14

Common challenges include:

• Legacy extension architecture
• Unsupported PHP versions
• Deprecated TYPO3 APIs
• Removed hooks and database methods
• Old TCA structures

TYPO3 Rector can automate many refactoring tasks, but TYPO3 7 projects often still require manual cleanup, extension replacements, and additional testing.

How Much Time Can TYPO3 Rector Save?

The biggest advantage of TYPO3 Rector is reducing repetitive migration work.

Typical estimates in 2026:

TYPO3 Rector does not eliminate testing or QA, but it can automate a large percentage of repetitive TYPO3 upgrade tasks and help teams focus more on validation instead of manual refactoring.

Best Practices for TYPO3 Rector

To get safer and more reliable TYPO3 upgrades with TYPO3 Rector, follow these best practices:

• Apply TYPO3 upgrades incrementally
• Run TCA migrations separately when possible
• Always use Git version control
• Start with --dry-run mode
• Test after every migration step
• Exclude vendor and public asset folders
• Keep TYPO3 Rector updated regularly
• Never run Rector directly on production

TYPO3 Rector automates repetitive migration work, but manual testing and QA should always remain part of the upgrade process.

Conclusion

TYPO3 Rector has transformed how developers handle TYPO3 upgrades in 2026. Instead of spending days manually fixing deprecated APIs and comparing changelogs, teams can automate much of the repetitive migration work and focus more on testing and validation.

TYPO3 Rector is not a complete replacement for QA, debugging, or architectural decisions. But it significantly reduces upgrade effort, improves consistency, and helps modernize TYPO3 projects faster.

For long-term TYPO3 maintenance, automated upgrade workflows help reduce technical debt, improve PHP compatibility, and make future TYPO3 migrations far more manageable.