Rector migration

Automatic migration of Neos 8.3 packages

To ensure the smoothest possible upgrade path, we offer a migration to be run using Rector.

The Rector migration is applied to your custom packages and rewrites the PHP source code to Neos 9 accordingly.

Manual action required

As not all places can get migrated automatically, the migration will also add "todos" for you, where a manual change is required.

// TODO 9.0 migration: Line 26: You very likely need to rewrite ...

#How to use Rector

#Installation

Please install the neos/rector package in your Distribution as a dev dependency with composer.

Note: This has changed to previous versions of this package.

# inside your Distribution folder
composer require --dev neos/rector:dev-main
cp Packages/Libraries/neos/rector/rector.template.php rector.php

#Configuration

Now, open up the rector.php file copied above, and adjust the Rector Paths (these are the paths which shall be migrated). By default, all of ./DistributionPackages will be migrated.

Right now, we ship the following sets of Rector rules:

\Neos\Rector\NeosRectorSets::CONTENTREPOSITORY_9_0: all rules needed to migrate to the Event-Sourced Content Repository (Neos 9.x)

Depending on your targeted version, you must choose one of the given rulesets within your rector.php config file.

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->sets([
        NeosRectorSets::CONTENTREPOSITORY_9_0,
    ]);

    $rectorConfig->paths([
        // TODO: Start adding your paths here, like so:
        __DIR__ . '/DistributionPackages/'
    ]);
};

#Running

Run the following command at the root of your distribution (i.e. where rector.php is located).

# for trying out what would be done
./rector/vendor/bin/rector --dry-run

# for running the migrations
./rector/vendor/bin/rector

Check the migrated code thoroughly and try to solve all open TODOs, which are generated by the rector migration.

neos/rector package repository