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, Fusion and YAML configurations 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

As Rector has strict dependency requirements, which might not match your own project, we strongly recommend to install neos/rector in a dedicated directory and not to add it to your project.

You can install the neos/rector package with composer as a dedicated package within your distribution.

# within the root of your distribution
composer create-project neos/rector:dev-main --stability=dev rector
cp 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) (currently still in progress)
\Neos\Rector\NeosRectorSets::NEOS_8_4: all rules needed if you want to upgrade already some code to prepare your Neos 8.4 for Neos 9.x. (currently still in progress)

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,
        //NeosRectorSets::NEOS_8_4
    ]);

    $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

Rector and PHP 8.4

In case you are working with PHP 8.4, you must use to PHP 8.3 to install and run Rector. Sadly the version we rely on is not compatible with PHP 8.4 and will not even install.

neos/rector package repository