This package contains a Rector ruleset which is used for migrating from Neos 8.x to 9.0 (and possibly also further up).
It will eventually replace Core/Code Migrations (./flow flow:core:migrate), but right now it is still in Development.
Right now we focus especially on rules to migrate from the old Content Repository API (< Neos 9.0) to the Event Sourced Content Repository (>= 9.0).
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.
# inside your Distribution folder
composer create-project neos/rector:dev-main --stability=dev rector
cp rector/rector.template.php rector.php
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
(currently still in progress)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
(This section is not relevant for users, but for developers of the Neos Rector packages)
Make sure to run Rector with the --clear-cache
flag while developing rules, when you run them on a full codebase.
Otherwise, ...
We develop all Rector Rules completely test-driven.
The test setup runs completely local; does not need any Distribution set up.
# if inside a Neos Distribution, change to the Package's folder
cd rector
# install PHPunit
composer install
# run PHPUnit
composer test
We extended Rector specifically for migrating Fusion files, by providing a FusionFileProcessor
and a FusionRectorInterface
which you can implement if you want to build Fusion transformations.
The Fusion Rectors will usually use one of the following tooling classes:
EelExpressionTransformer
: for finding all Eel expressions inside Fusion and AFX; and transforming them in some way.The Fusion and AFX Parsing functionality is based on the official Fusion and AFX parsers. However, the classes are
vendored/copied into this package by the ./embed-fusion-and-afx-parsers.sh
script, because of the following reasons:
The Fusion parser was subclassed by Neos\Rector\Core\FusionProcessing\CustomObjectTreeParser
for retaining position
information of AFX and Eel Expressions.
Updating Fusion and AFX Parser
To update the vendored Fusion and AFX parsers, run the ./embed-fusion-and-afx-parsers.sh
script.
Updating the AFX Parser Patch
The AFX parser needs a custom patch (see ./scripts/afx-eel-positions.patch
) to retain positions.
To create/update this patch, do the following:
cd Packages/Neos
# apply the current patch
patch -p1 < ../../rector/scripts/afx-eel-positions.patch
# Now, do your modifications as needed.
# when you are finished, create the new patch
git diff -- Neos.Fusion.Afx/ > ../../rector/scripts/afx-eel-positions.patch
# ... and reset the code changes inside Neos.Fusion.Afx.
git restore -- Neos.Fusion.Afx/
composer run generate-docs