Funding Request: Future proof Fusion and PHP 8.4 compatible Neos 9.0 migrations

Marc · October 1, 2025, 1:33pm

A funding request for house keeping and maintenance - preserving the status quo.

With the release of Neos 9.0 we provide a code migration tool in the form of neos/rector for migrating Fusion, YAML and PHP files.
The used dependencies are now aged as the migration tool was created already years before the release. With the advent of PHP 8.4 the dependencies show its age as it is simply incompatible. In the extensive discussion on the first of august Bastian, Christian, Denny and Marc Henry the conclusion was drawn that it is important to support PHP 8.4 for the current migrations and also for the future ones.

It was agreed to upgrade the migration tool to use the new rector dependency for PHP migrations and fully rewrite the Fusion migrations to be part of Flow migration Framework. Estimated it will take 6 to 8 days of work.

More technical information is available in this github issue:

github.com/neos/neos-development-collection

Updating to Neos 9 - code migrations - `neos/rector` vs `flow:core:migrate`

opened 06:30PM - 03 Aug 25 UTC

mhsdesign

For the upgrade of Neos 8.3 to Neos 9.0 we leverage [rector](https://getrector.c…om/) as it parses the php files and uses static analysis to understand the code. We can migrate complex code as we are aware of the variable types and we produce valid php code at all times. Before that we relied on the flow migration framework which only offers simple regex/text replace which is doomed for failures. Further we also provide migrations to migrate EEL expression in fusion files. This works by parsing the fusion and afx code and finding within it all EEL expressions - regex is then used to rename within the expressions function names or other simple parts. This is more advanced than replacing text across the whole fusion file without knowing if it is inside of an eel expression, but as we dont parse EEL and are not aware of the variable types we cannot always succeed. ### Current state At the moment we leverage a dedicated package `neos/rector` for php and fusion migrations. Users will need to follow the instructions from https://docs.neos.io/api/upgrade-instructions/version-9-x/upgrade-instructions-8-3-9-0/rector-migration to install rector separately next to neos. The readme states: > This package contains a Rector ruleset which is used for migrating from Neos 8.x to 9.0 (and lateron also further up). > > It will eventually replace Core/Code Migrations (./flow flow:core:migrate) (which are not used anymore for migrating to Neos 9 and further). > > 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). Fusion migrations are realised via an extension point of rector to process other files. The neos rector package provides a copy of a slightly modified version of the neos fusion parser and afx parser as described: https://github.com/neos/rector/blob/e1260d99200f7f600529188121308d43caf3751e/README.md?plain=1#L89 We have been using zero-dot releases (version `0.x`) of rector and now the stable versions 1 and 2 are available. Rector changed its api how to write php migrations and it also removed the ability to add custom file processors like we do for fusion (https://github.com/rectorphp/rector-src/pull/4808). This has limited us in the past to update. Because we lack behind we were only able to distribute rector separately as otherwise the old betas dependencies would collide with the neos distribution. For the neos 9 release we did discuss in our weekly at the 2024-05-10 to keep the status quo and distribute rector separately. But for fusion we have to evaluate separate ways. ### Problems The ad-hoc solution to install neos/rector fully separated does work mostly - except its not compatible with PHP 8.4. To update rector we need to reimplement the fusion migration somehow. ### Our weekly discussion from 2025-08-01 _bastian,christian,denny,marc henry_ #### Do we need to be PHP 8.4 compatible in the migrations - aren't the 9.0 migrations mostly applied while php 8.3 is primarily used? Technically the limitation is bearable because we only require the `neos/rector` package to be executed via PHP 8.3 - we dont impose that role for the actual neos installation. But developers dont necessarily have a PHP 8.3 binary at hand immediately which introduces additional friction. #### Arent the migrations throw away code - do we really need to migrate the migrations to the new rector? We also expect not all projects to update from 8.3 to Neos 9.0 but that many users will target the Neos 9.3 LTS version. The Neos 9.1 and 9.x might also introduce new rector migrations - requiring users to update first to Neos 9.0 with the legacy rector to then use a new version of `neos/rector` would introduce much trouble. Also at that time the mentioned PHP 8.3 might already be out of support for all what we can know:) #### Are we really going to replace the flow core migrations? How does our rector ecosystem work if plugins want to provide migrations? Because rector is so revolutionary we agreed in the past that with rector "will eventually replace Core/Code Migrations (./flow flow:core:migrate)". But there is no full concept for this yet and also the changes in rector could change that path. Our rector package only works as one not extensible set of migrations. Technically we could merge the rule set config with config of other packages but that is manual work at this moment. *Solution* We concluded that in terms of effort and simplicity we should instead just revive the only called dead flow core migrations. Because flow already provides tooling for the whole eco system which we just have to extend in its functionality that to replace it. The concrete idea is to introduce an `AbstractFusionMigration` (or some helper trait) which handles the fusion migration that is not allowed to be part of rector anymore. For rector we discussed triggering that in turn also from flow, but this bring challenges in terms that rector has to be definitely always be installed as dev dependency (via base distribution) alongside flow and the migration files providing rector rules would have an dependency on the rector version again which is troubling as that cannot be guaranteed - also if rector moves to fast we are where were now. A simple turn is to keep the php migration in `neos/rector` but update them to rector 2 (see pr https://github.com/neos/rector/pull/147) ### ... WIP ... i missed some things, this is just the starting from the top of my head. Todo: - superfluous core migrate entries in composer json (especially with packages that are not related) - automatic migration vs explicit vs fully manual -

Who could work on this?

@lubitz
@Marc
maybe @christianm ?
you?

What do we need?

We apply for 6.400€ of funding from the Neos Foundation.

Yes
Abstain
No

0 voters

Please give your feedback and/or vote until 9 Oktober 2025.

Thank you
Gratefully the Neosianer Denny and Marc Henry

sebobo · October 7, 2025, 9:03am

Is part of this already done or can be reused with the Fusion migrations we now have in 8.4?

Marc · October 8, 2025, 12:27pm

This is the current state of the Project:

The Neos 8.4 release is around the corner. And we decided and back-ported some of the Neos 9.0 Node-Fusion changes like node.aggregateId.

To turn 8.4 into a fully sound migration preparation update - and as we want to turn the neos/rector migrations into Fusion Core migrations in Neos.Neos for Neos 9.0 - i prepared the integration of the Fusion migrations for the 8.4 branch to make them available already for early adopters in Neos 8.4.

This is the initial change: FEATURE: Fusion (EEL) core migrations for new 9.0 API (replaces neos/rector for Fusion)

Behaviour for Neos 8.4

Introducing a core migration for 8.4 was considered but was found to be too magic as its truly an optional step which makes the code not backwardscompatible to previous neos versions.

Instead the adjustments can be run manually via flow command. They will not add todo comments like the 9.0 migration as those are hardly solveable in Neos 8.4. It will be safe to rerun this migration and also to run the 9.0 migration via flow:core:migrate when updating.

./flow neos9preparation:preadjustfusion Neos.Demo

(Prepared) Behaviour for Neos 9.0

The change introduces a “disabled” migration which will be enabled during the upmerge to 9.0. The migration “20251005080230” contains all fusion migrations concerning the content repository that currently reside in neos/rector and were executed with rector.

They will be part of “Neos.Neos” and can be executed as any flow core migration:

flow flow:core:migrate Neos.Demo --version 20251005080230

The comprehensive testsuite for this cr-fusion migration was copied and adjusted from neos/rector to ensure all replacements work as desired.

Behaviour for Neos 8.4 and 9.0

Neos 8.4 now also migrates the legacy prototypes Neos.Fusion:Attributes and Neos.Fusion:Collection in fusion and emits warnings and writes todo comments when there is no automatic way:

this migration will be already be part of the core migrations starting with 8.4 as the fusion objects have been deprecated since ages with replacements available.

Via up-merge they will also be available in Neos 9.0 and thus replace neos/rector here in the future.

Demonstration that the todo comments are not only written to the files but also output as flow migration warnings. Additionally running the migration twice will not write the todo comments again to avoid having comments stack on top of previous comments - the warnings will still be shown in the terminal.

So far i have worked 2 days on this project in October.

So yes @sebobo this is all going according to my masterplan;)

Marc · October 9, 2025, 1:05pm

Thank you for the votes.

Seeing there was a full agreement on the budget via 10 votes and no further questions the budget is considered granted.

Marc · October 9, 2025, 1:17pm

A little update:

The fusion migrations were further refined via this change to be more careful when rewriting expressions and Neos 8.4 now provides the remaining runtime utilities to allow the new fusion code to work.

github.com/neos/neos-development-collection

TASK: Add missing fusion migrations and runtime helper for 9.0

8.4 ← feature/add-missing-fusion-migrations-and-runtime-helper

opened 09:37AM - 08 Oct 25 UTC

mhsdesign

+612 -449

Followup to https://github.com/neos/neos-development-collection/pull/5638 I d…id a full re-review on all the Fusion migrations that were copied from `neos/rector` The Fusion migrations were refined to ensure we handle even more cases (and in 9.0 write comments for all the things) Doing that i noticed we were missing the 8.4 api for `node.workspaceName` and `node.classification.tethered` and `q(node).property("hiddenInMenu")` and ~enableAfterDateTime, disableAfterDateTime~ so i added the missing runtime layers for those too. **Upgrade instructions** **Review instructions** **Checklist** - [ ] Code follows the PSR-2 coding style - [ ] Tests have been created, run and adjusted as needed - [ ] The PR is created against the [lowest maintained branch](https://www.neos.io/features/release-roadmap.html) - [ ] Reviewer - PR Title is brief but complete and starts with `FEATURE|TASK|BUGFIX` - [ ] Reviewer - The first section explains the change briefly for change-logs - [ ] Reviewer - Breaking Changes are marked with `!!!` and have upgrade-instructions

Sebastian and me re-evaluated today if we want to add a deprecation log for deprecated EEL Expressions in 8.4 but we decided that it would be of no gain for our users.
The log is already part of Neos 9 via FEATURE: Fusion eel neos deprecation tracer by mhsdesign · Pull Request #5262 · neos/neos-development-collection · GitHub

Following problems make the logs invaluable and impractical for Neos 8.x:

we have no idea in the fusion runtime where the eel expression was defined as this information is not preserved
we have not migrated our Neos.Neos package to use non deprecated apis - this is not even possible for all cases. The log is thus already swamped with logs from Neos where users have no influence.
we would need to adjust Neos.Neos as good as possible and also other packages like Neos.Seo and give them a minor release which will be lots of work.
we could store the information where the eel expression was defined - topic source maps in fusion - and thus ignore all logs from “Neos.*”
→ but users are in the end faced with the same problem we have and will not be able to migrate all cases like node.context.dimensions already to non deprecated syntax as 8.4 lacks the replacements.

While it might be easy for a simple page to satisfy the log - a complex site has no chance to become fully 9.0 compatible and especially not with the mentioned problems above. Thus we will not backport this feature - and thus preventing to swamp our users logs;)