Table of Contents

1. Examples in action
2. Overview of all rules
3. Installation
4. Configuration and Processing
5. Best practice guide
6. Limitations
7. Contribution

Best practice guide

Version matrix:

What to use for

You can use TYPO3 Rector in various ways:

• checking existing code if there are left-out segments of the last upgrade
• evaluate upgrades and see what parts of your custom setup will be updated automatically
• partial execution of full core upgrades

Guide for a good upgrade

TLDR;

• apply older or current version rulesets first (if you're going from v10 to v12, apply v7/v8/v9/v10 sets first)
• if possible start with version 2 of typo3-rector because it has the bugfixes and all rules from version 10 to 13 of TYPO3
• add ClassAliasMap in case you're upgrading two versions to provide old classes to migrate (see ClassAliasMap)
• apply rulesets stepwise by version; first TCA only, then full set or combined
• apply rulesets stepwise to your packages or multiple packages at once

Starting

Starting with an upgrade should start with installing TYPO3 Rector and checking for the rector rules/sets of your current version, not the one you're targeting. Often there are things that were missed out in previous upgrades while rector adds rulesets for those.

If you're on TYPO3 v8 you should start with applying the rulesets for v7 first and v8 afterwards.

Examples for often missed out upgrade steps:

• ext:lang key changes OR the full ext:lang replacement
• TCA renderType addition on type="single"
• TCA fieldwizard OR overrideChildTCA rewrite

Ongoing upgrade

After making sure your current code base is properly upgraded, you go on with the actual upgrade process. This requires manual action like allowing the core versions in your composer.json and ext_emconf.php files depending on your individual setup.

Applying rulesets

Depending on the amount of version steps you should add the ClassAliasMap as mentioned above for e.g. v8 if you're going from v8 to v10 directly.

Once again, you add your wanted/needed rulesets that should be separated by version. It also comes in handy to divide between TCA and TYPO3 changes AND/OR your packages.

The TYPO3 sets always include the TCA sets!

TCA changes are often not that big in their impact but necessary. Also, custom packages do not necessarily provide that much own TCA. Both of that is a reason to gather multiple packages for a combined TCA run with the following config:

return RectorConfig::configure()
    ->withSets([
        Typo3SetList::TCA_95
    ])
    ->withPaths([([
        __DIR__ . '/packages/package_one',
        __DIR__ . '/packages/package_two',
        __DIR__ . '/packages/package_three',
    ]);

ClassAliasMap

The ClassAliasMap is a TYPO3 specific feature. It is used to allow migration of no longer existing class names to new class names. Rector is not able to load the necessary ClassAliasMap on demand. Those need to be provided via extra section inside composer.json of the project:

{
    "extra": {
        "typo3/class-alias-loader": {
            "class-alias-maps": [
                "vendor/ssch/typo3-rector/Migrations/TYPO3/10.4/typo3/sysext/backend/Migrations/Code/ClassAliasMap.php",
                "vendor/ssch/typo3-rector/Migrations/TYPO3/10.4/typo3/sysext/core/Migrations/Code/ClassAliasMap.php",
                "vendor/ssch/typo3-rector/Migrations/TYPO3/12.0/typo3/sysext/backend/Migrations/Code/ClassAliasMap.php",
                "vendor/ssch/typo3-rector/Migrations/TYPO3/12.0/typo3/sysext/frontend/Migrations/Code/ClassAliasMap.php"
            ]
        }
    }
}

Provide the ClassAliasMap files of all necessary extensions for all necessary versions.

Limitations

There are limitations to the TCA detection.

TYPO3 Rector can only detect TCA if the TCA is valid, which means there is a 'ctrl' and a 'columns' key:

return [
    'ctrl' => [],
    'columns' => [],
];

So to migrate your TCA in Configuration/Override/ it is required to add those keys.

Also we can only migrate, when the type of the TCA column is known. For overrides this means you have to add it, e.g. when you extend the doktype items.

$pages = [
    'columns' => [
        'doktype' => [
            'items' => [
                ['foo', 'foo']
            ],
        ],
    ],
];

add 'type' => 'select to migrate with rector

The non-TCA rules are often a little more specific and should be applied in a separate step with the according set, e.g. Typo3SetList::TYPO3_95.

Those rules bring immense value as you don't have to find the replacement of classes and the actual changelog as it is provided for you already on execution. With --dry-run you can process the ruleset without applying the changes giving you a perfect overview before changing your code.

You can focus on testing and possibly learning the new implementation of previous functions.

Special cases

There are changes that TYPO3 Rector knows of but cannot fully complete.