Automate TYPO3 Upgrades: Complete Rector Guide 2025

Published on :  
Starke Brandt
Update

Automate TYPO3 Upgrades: Complete Rector Guide 2025

Stop spending days on manual TYPO3 upgrades. TYPO3 Rector automates code migrations, handles deprecations, and updates TCA configurations automatically. Focus on testing instead of tedious copy-paste work.

TYPO3 upgrades used to mean days of manual code changes. Copy-pasting from changelogs. Finding deprecated methods one by one. Testing everything twice.

Not anymore.

TYPO3 Rector automates the boring stuff. It reads TYPO3 changelogs and rewrites your code automatically. You focus on testing instead of hunting down deprecated functions.

A Quick Thanks;

Thanks to Sebastian Schreiber (@sabbelasichon) and the TYPO3 Rector community for building this tool. You turned painful TYPO3 upgrades into something manageable. I want to dedicate this blog to the team TYPO3 rector.

This guide is for every developer who's spent weekends manually fixing deprecated code. You deserve better tools.

What is TYPO3 Rector?

TYPO3 Rector Transformation

TYPO3 Rector extends the Rector project to provide instant upgrades and refactoring for TYPO3 websites and extension code. It makes migrating between TYPO3 releases easier by keeping your code free from deprecation.

Think of it as your personal code migration assistant. It knows every breaking change in TYPO3 history and can fix them automatically.

Here's what it handles:

  • PHP code updates
  • TCA configuration changes
  • Class name replacements
  • Method signature updates
  • Configuration format changes

Why Use TYPO3 Rector?

TYPO3 Rector

Manual TYPO3 upgrades are painful. You spend hours reading changelogs, finding affected code, and making repetitive changes.

TYPO3 Rector eliminates most of this work:

Time savings: What took days now takes minutes Error reduction: No more missed deprecations Consistency: Same rules applied everywhere Documentation: Changes are based on official TYPO3 changelogs Testing focus: Spend time testing features, not finding bugs.

Requirements and Compatibility

Safe tool usage cycle

Before starting, check your environment:

PHP Requirements:

  • PHP 7.4 minimum (PHP 8.1+ recommended)
  • Composer installed
  • Git version control (essential for safety)

TYPO3 Compatibility:

  • TYPO3 v7 to v13 supported
  • Works with custom extensions
  • Compatible with third-party extensions

Important Safety Note: Never run this tool on production! Always run it on development environment where code is under version control. Review and test changes before releasing to production.

Installation Guide

Method 1: Global Installation (Recommended)

Install TYPO3 Rector globally to use across multiple projects:

composer global require ssch/typo3-rector

Add Composer's global bin directory to your PATH:

# Add to your ~/.bashrc or ~/.zshrc
export PATH="$PATH:$HOME/.composer/vendor/bin"

Verify installation:

typo3-rector --version

Method 2: Project-specific Installation

For project-specific usage:

composer require --dev ssch/typo3-rector

Method 3: PHAR Download

Download the standalone PHAR file:

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

Basic Configuration

Create a rector.php configuration file in your project root:

<?php

declare(strict_types=1);

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

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/typo3conf/ext/your_extension',
        // Add more paths as needed
    ])
    ->withSets([
        Typo3SetList::TYPO3_95,
        Typo3SetList::TYPO3_104,
        Typo3SetList::TYPO3_11,
        Typo3SetList::TYPO3_12,
    ])
    ->withSkip([
        // Skip specific files or directories
        __DIR__ . '/typo3conf/ext/your_extension/Resources',
    ]);

Configuration Options

Paths: Define which directories to process

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

Sets: Choose TYPO3 version-specific rule sets

->withSets([
    Typo3SetList::TYPO3_76,      // For v7.6 migrations
    Typo3SetList::TYPO3_87,      // For v8.7 migrations  
    Typo3SetList::TYPO3_95,      // For v9.5 migrations
    Typo3SetList::TYPO3_104,     // For v10.4 migrations
    Typo3SetList::TYPO3_11,      // For v11 migrations
    Typo3SetList::TYPO3_12,      // For v12 migrations
    Typo3SetList::TYPO3_13,      // For v13 migrations
])

Skip: Exclude files or directories

->withSkip([
    __DIR__ . '/vendor',
    __DIR__ . '/typo3',
    '*/Resources/Private/Vendor/*',
])

Running Your First Migration

Step 1: Backup Your Code

Always work with version control:

git add .
git commit -m "Backup before Rector migration"

Step 2: Dry Run

See what changes Rector would make without applying them:

typo3-rector process --dry-run

This shows you exactly what will change. Review the output carefully.

Step 3: Apply Changes

Run the actual migration:

typo3-rector process

Step 4: Review Changes

Check what was modified:

git diff

Step 5: Test Everything

Run your tests and manually verify critical functionality works.

Common Use Cases

Upgrading from TYPO3 v10 to v11

// rector.php
return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/typo3conf/ext/your_extension',
    ])
    ->withSets([
        Typo3SetList::TYPO3_11,
    ]);

Common changes this handles:

  • GeneralUtility::getFileAbsFileName() parameter changes
  • TCA renderType updates
  • Signal/Slot to PSR-14 events conversion

Migrating Custom Extensions

// rector.php for extension development
return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/Classes',
        __DIR__ . '/Configuration',
    ])
    ->withSets([
        Typo3SetList::TYPO3_12,
        Typo3SetList::TYPO3_13,
    ])
    ->withSkip([
        __DIR__ . '/Resources',
        __DIR__ . '/Documentation',
    ]);

Full Project Migration

For complete site migrations:

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/typo3conf/ext',
        __DIR__ . '/packages',
    ])
    ->withSets([
        Typo3SetList::TYPO3_95,
        Typo3SetList::TYPO3_104,
        Typo3SetList::TYPO3_11,
        Typo3SetList::TYPO3_12,
    ])
    ->withSkip([
        '*/Resources/Private/Vendor/*',
        '*/node_modules/*',
        '*/Resources/Public/JavaScript/Contrib/*',
    ]);

Advanced Configuration

Custom Rules

Add specific Rector rules beyond TYPO3 sets:

use Rector\Php74\Rector\Property\TypedPropertyRector;
use Rector\DeadCode\Rector\ClassMethod\RemoveUnusedPromotedPropertyRector;

return RectorConfig::configure()
    ->withRules([
        TypedPropertyRector::class,
        RemoveUnusedPromotedPropertyRector::class,
    ])
    ->withSets([
        Typo3SetList::TYPO3_12,
    ]);

Parallel Processing

Speed up processing with parallel execution:

return RectorConfig::configure()
    ->withParallel()
    ->withPaths([
        __DIR__ . '/typo3conf/ext',
    ]);

Memory Limits

For large projects, increase memory:

return RectorConfig::configure()
    ->withMemoryLimit('2G')
    ->withPaths([
        __DIR__ . '/typo3conf/ext',
    ]);

Best Practices

1. Incremental Migrations

Don't jump multiple versions at once. Migrate step by step:

# Wrong: Skip versions
typo3-rector process --set=typo3-95,typo3-12

# Right: Step by step
typo3-rector process --set=typo3-95

# Test, commit, then continue
typo3-rector process --set=typo3-104

# Test, commit, then continue
typo3-rector process --set=typo3-11

2. Separate TCA and Code Rules

The non-TCA rules are often more specific and should be applied in a separate step with the according set.

Run TCA migrations separately:

// First: TCA migrations
return RectorConfig::configure()
    ->withSets([
        Typo3SetList::TCA_120,
    ]);

Then code migrations:

// Second: Code migrations  
return RectorConfig::configure()
    ->withSets([
        Typo3SetList::TYPO3_12,
    ]);

3. Use Version Control Effectively

Create meaningful commits:

git add .
git commit -m "Apply TYPO3 v11 Rector rules"

git add .
git commit -m "Apply TYPO3 v12 Rector rules"

4. Test After Each Step

Never apply multiple rule sets without testing:

  • Apply one rule set
  • Run tests
  • Fix any issues
  • Commit changes
  • Repeat with next rule set

Troubleshooting

Common Issues

Out of Memory Errors:

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

Timeout on Large Projects:

return RectorConfig::configure()
    ->withMemoryLimit('2G')
    ->withParallel(4); // Adjust based on CPU cores

False Positives:
Skip problematic rules:

return RectorConfig::configure()
    ->withSkip([
        SpecificRectorRule::class,
        SpecificRectorRule::class => [
            __DIR__ . '/specific/file.php',
        ],
    ]);

Debug Mode

Get detailed information about what Rector is doing:

typo3-rector process --debug

Xdebug Integration

For development and debugging:

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

Real-World Examples

Example 1: Signal/Slot to PSR-14 Events

Before (TYPO3 v10):

$dispatcher = GeneralUtility::makeInstance(Dispatcher::class);
$dispatcher->connect(
    DataHandler::class,
    'processDatamap_afterDatabaseOperations',
    MyClass::class,
    'handleAfterDatabaseOperations'
);

After (TYPO3 v11):

// In Services.yaml
services:
  MyVendor\MyExtension\EventListener\AfterDatabaseOperationsEventListener:
    tags:
      - name: event.listener
        identifier: 'my-after-database-operations'
        event: TYPO3\CMS\Core\DataHandling\Event\AfterDatabaseOperationsEvent

Example 2: TCA Changes

Before:

$GLOBALS['TCA']['pages']['columns']['doktype']['items'][] = [
    'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:pages.doktype.custom',
    123,
    'EXT:my_extension/Resources/Public/Icons/custom.svg'
];

After:

$GLOBALS['TCA']['pages']['columns']['doktype']['items'][] = [
    'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:pages.doktype.custom',
    'value' => 123,
    'icon' => 'EXT:my_extension/Resources/Public/Icons/custom.svg'
];

Example 3: Utility Method Changes

Before (TYPO3 v11):

$absPath = GeneralUtility::getFileAbsFileName('EXT:my_extension/Resources/Private/Templates/');

After (TYPO3 v12):

$absPath = GeneralUtility::getFileAbsFileName('EXT:my_extension/Resources/Private/Templates/') ?: '';

Integration with CI/CD

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.1
          
      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader
        
      - name: Run Rector
        run: vendor/bin/typo3-rector process --dry-run

GitLab CI

rector:
  image: php:8.1
  script:
    - composer install --no-dev
    - vendor/bin/typo3-rector process --dry-run
  only:
    - merge_requests

Performance Optimization

Large Projects

For projects with thousands of files:

return RectorConfig::configure()
    ->withParallel(8)
    ->withMemoryLimit('4G')
    ->withPaths([
        __DIR__ . '/typo3conf/ext',
    ])
    ->withSkip([
        '*/Tests/*',
        '*/Documentation/*',
        '*/Resources/Public/*',
    ]);

Selective Processing

Process only changed files:

# Get list of changed PHP files
CHANGED_FILES=$(git diff --name-only --diff-filter=AM main...HEAD | grep '\.php$')

# Run Rector only on changed files
typo3-rector process $CHANGED_FILES

Maintenance and Updates

Keep TYPO3 Rector Updated

composer global update ssch/typo3-rector

Check for New Rules

New rules are added regularly. Check the changelog:

typo3-rector --version

Visit the GitHub releases for update notes.

Working with Fractor

Other file types like TypoScript, XML (FlexForm) and composer.json are supported by Fractor which plays nicely together with TYPO3 Rector.

Install Fractor for non-PHP files:

composer require --dev a-r-m-i-n/fractor

Example Fractor configuration:

// fractor.php
use TYPO3\Fractor\Configuration\FractorConfiguration;

return FractorConfiguration::configure()
    ->withFileExtensions(['typoscript', 'ts', 'txt'])
    ->withPaths([
        __DIR__ . '/Configuration/TypoScript',
    ]);

Common Rector Rules Explained

Database Connection Updates

Rule: DatabaseConnectionToEntityManagerRector

Converts old database connections to Doctrine DBAL:

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

// After  
GeneralUtility::makeInstance(ConnectionPool::class)
    ->getConnectionForTable('pages')
    ->select(/* ... */);

Hook to Event Conversion

Rule: Various event migration rules

Converts hooks to PSR-14 events:

// Before
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][] = 'MyClass';

// After
// Event listener registration in Services.yaml

TCA Migration Rules

Rule: TcaItemsArrayToAssociativeArrayRector

Modernizes TCA configuration:

// Before
'items' => [
    ['Label', 'value'],
]

// After
'items' => [
    ['label' => 'Label', 'value' => 'value'],
]

Extending TYPO3 Rector

Custom Rules

Create custom rules for project-specific migrations:

<?php

namespace MyVendor\MyExtension\Rector;

use Rector\Core\Rector\AbstractRector;
use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;

final class MyCustomRector extends AbstractRector
{
    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition(
            'Replace custom deprecated method',
            [/* examples */]
        );
    }

    public function getNodeTypes(): array
    {
        return [MethodCall::class];
    }

    public function refactor(Node $node): ?Node
    {
        // Your custom refactoring logic
        return $node;
    }
}

Contributing Rules

Help the community by contributing rules:

Conclusion

TYPO3 Rector transforms how you handle TYPO3 upgrades. Instead of manual migrations taking days, you get automated code updates in minutes.

The tool isn't perfect. You'll still need to test thoroughly and handle edge cases manually. But it eliminates 80-90% of the tedious work.

Start small. Pick one extension and run a dry-run. See what it finds. Then gradually expand to your full project.

Your future self will thank you for setting this up now. Every TYPO3 upgrade becomes routine instead of a multi-day project.

Remember the golden rules:

  • Always use version control
  • Never run on production
  • Test everything after migration
  • Apply changes incrementally
  • Keep TYPO3 Rector updated

Use TYPO3 Rector for automated code upgrades of your TYPO3 website based on the official changelogs of TYPO3. Focus on testing instead of copy+paste.

Resources and Links

Last updated: August 2025. TYPO3 Rector continues active development with regular updates for new TYPO3 versions.

FAQ

TYPO3 Rector is an automated code migration tool that upgrades and refactors TYPO3 PHP code instantly. It reads official TYPO3 changelogs and automatically fixes deprecated methods, updates TCA configuration, and handles breaking changes between TYPO3 versions. Instead of manually searching for deprecated code, TYPO3 Rector does the work for you.

Install TYPO3 Rector globally using Composer: composer global require ssch/typo3-rector. Then add Composer's global bin directory to your PATH. Alternatively, install it per project with composer require --dev ssch/typo3-rector. Create a rector.php config file in your project root, define paths and TYPO3 version sets, then run typo3-rector process.

TYPO3 Rector is safe when used properly with version control. Never run it directly on production code. Always use it on development environments where code is under Git version control. Run with --dry-run first to see what changes it will make. Review all changes carefully, test thoroughly, and commit incrementally after each migration step.

TYPO3 Rector supports migrations from TYPO3 v7.6 to v13. Available version sets include TYPO3_76, TYPO3_87, TYPO3_95, TYPO3_104, TYPO3_11, TYPO3_12, and TYPO3_13. You should migrate step by step through each version rather than jumping multiple versions at once. Each set handles the specific breaking changes and deprecations for that TYPO3 version.

No, never use TYPO3 Rector directly on production servers. TYPO3 Rector modifies code files and should only run in development environments. Use it locally or on staging servers with full version control. After testing the changes thoroughly, deploy the updated code to production through your normal deployment process. This ensures safety and allows you to rollback if issues occur.

Get hassle-free upgrade service from a certified TYPO3 Developer

  • 350+ Extensions upgrade to TYPO3 LTS versions
  • 150+ Completed TYPO3 upgrade sites (from v6 to current LTS)
  • 35+ Team of TYPO3 developers
  • 13+ Years of TYPO3 experience
  • 3 Package plans are available for the TYPO3 upgrade
  • 2 Days of quick support (reaction and resolution time)
TYPO3 Upgrade Gig
upgrade
Starke Brandt

Starke Brandt

Brand & Communication Lead

Starke shapes the voice of T3Planet — and it shows. With years of TYPO3 experience in marketing and product branding, he ensures everything we publish reflects clarity, credibility, and purpose. He’s the reason our content…

More From Author

Previous Article
Official Launch of the TYPO3 Accessibility Extension
Next Article
Privacy-First Analytics & Consent in TYPO3 (DACH-Ready)

Post a Comment

×

You May Also Like

Thoughts on TYPO3 v14: Strategic Vision & Road Map Highlights

Thoughts on TYPO3 v14: Strategic Vision & Feature Highlights

Starke Brandt
Starke Brandt
Update
Everything You Need to Know About TYPO3 CMS v13

TYPO3 v13 - Everything You Need to Know

Starke Brandt
Starke Brandt
Update
25+ Key Changes of TYPO3 v13.3

25+ Key Changes of TYPO3 v13.3

Starke Brandt
Starke Brandt
Update