neos / rector

Neos Rector Recipes for code migrations

Neos.Rector

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).

Installation

# 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 (currently still in progress)

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
./bin/rector --dry-run

# for running the migrations
./bin/rector

Developing Rector Rules for Neos

(This section is not relevant for users, but for developers of the Neos Rector packages)

Running Rector after adjusting rules

Make sure to run Rector with the --clear-cache flag while developing rules, when you run them on a full codebase.

Otherwise,

Running Tests

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 Packages/Libraries/neos/rector

# install PHPunit 
composer install

# run PHPUnit
composer test

Fusion Rector

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.
• (more tooling classes to come here as we need them).

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:

• Rector needs to run even when Flow cannot compile the classes; so we cannot depend on a Flow package.
• We slightly need to patch the AFX parser, because we need position information for Eel Expressions.

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 < ../Libraries/neos/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/ > ../Libraries/neos/rector/scripts/afx-eel-positions.patch

# ... and reset the code changes inside Neos.Fusion.Afx.
git restore -- Neos.Fusion.Afx/

Generating docs

composer run generate-docs

rector's Issues

Migrate `Node::getNodeType`

neos/neos-development-collection#5020

Following code should be migrated:

- $node->getNodeTypeName();
+ $node->nodeTypeName;

- $node->getNodeType()->getName();
+ $node->nodeTypeName->value;

- $nodeType->getName();
+ $nodeType->name->value;

- $node->getNodeType();
+ $nodeTypeManger = ...;
+ $nodeTypeManager->getNodeType($node->nodeTypeName);

- $node->getNodeType()->getTypeOfAutoCreatedChildNode(NodeName::fromString('name'));
+ $nodeTypeManager->getTypeOfTetheredNode($node->nodeTypeName, NodeName::fromString('name'));

Special cases of `node.context.*`

• migrate node.context.currentSite to eel helper to fetch site entity
• migrate node.context.workspace to eel helper to fetch workspace, but attention, the workspace api in fusion also changed.
• warn if anything else is accessed by node.context.*
• while the renderingMode has a basic migration via #22, but the not all things are migrated currently
  • node.context.workspace.name == 'live' -> !renderingMode.isEdit
  • node.context.workspace.personalWorkspace -> renderingMode.isEdit
  • node.context.currentRenderingMode.* -> renderingMode.*

Remove NodeTypeManager from NodeType

See: neos/neos-development-collection#4520

the NodeTypeManager can provide replacements:

- $nodeType->getAutoCreatedChildNodes();
+ $nodeTypeManager->getTetheredNodesConfigurationForNodeType($nodeType);

- $nodeType->hasAutoCreatedChildNode($nodeName);
+ $nodeType->hasTetheredNode($nodeName);

- $parentsNodeType->getTypeOfAutoCreatedChildNode($nodeName);
+ $nodeTypeManager->getTypeOfTetheredNode($parentsNodeType, $nodeName);

- $grandParentsNodeType->allowsGrandchildNodeType($parentNodeName, $nodeType);
+ $nodeTypeManager->isNodeTypeAllowedAsChildToTetheredNode($grandParentsNodeType, NodeName::fromString($parentNodeName), $nodeType);

Rename _hiddenBeforeDateTime and _hiddenAfterDateTime in Fusion

_hiddenAfterDateTime => disableAfterDateTime
_hiddenBeforeDateTime => enableAfterDateTime

TASK: Add fusion migrations for usage of `node.identifier` and `node.nodeAggregateIdentifier`

Example of old usages:

@process.augment = Neos.Fusion:Augmenter {
  id = ${node.identifier}
}

@process.augment = Neos.Fusion:Augmenter {
  id = ${node.nodeAggregateIdentifier}
}

Example of usage in Neos 9:

@process.augment = Neos.Fusion:Augmenter {
  id = ${node.nodeAggregateId.value}
}

BUG: Rector migration for usage of `node.parent` doesn't work

• It will generate comments for lines that are using flow query operations like parent() or parents()
• The comment says You may need to rewrite "VARIABLE.parent" to Neos.NodeAccess.findParent(VARIABLE). But I found no matching eel helper.

Migrate `node.context.inBackend` to `Neos.Backend.isEditMode(request)`

Resolves partly neos/neos-development-collection#4396

As @mficzel said here neos/neos-ui#3571:

replace Neos.Node.inBackend(node) which is removed here neos/neos-development-collection#4067 with Neos.Backend.isEditMode(request) || Neos.Backend.isPreviewMode(request)

Currently node.context.inBackend is rewritten to Neos.Node.inBackend, but we might get rid of that method or deprecate it...

The question is if we should provide a Flow or rector migration for existing 9.0 projects using Neos.Node.inBackend? - could be a simple regex ^^ (or one needs to run this regex yourself via php storm.)

search

Neos.Node.inBackend\([a-zA-Z]*\)

replace with

Neos.Backend.isEditMode(request) || Neos.Backend.isPreviewMode(request)

TASK: 9.0 migrate `node.context.currentRenderingMode.edit`

node.context is not available anymore.

https://github.com/neos/neos-development-collection/blob/f4ed8369957209ba689cb2e1d9319e39716d6ac3/Neos.Neos/Resources/Private/Fusion/Prototypes/ContentCollection.fusion#L30

warn about `q(node).property('_path')` and `${node.path}` (the latter wont work either way)

Critical migrations

• NodeType::getName was removed neos/neos-development-collection#4560
  • migrate ${node.nodeType.name} to ${node.nodeTypeName.value} (not 100% equivalent but should mostly do)
  • migrate $nodeType->getName() to $nodeType->name->value
• #33
• #34
• #31
• #29
• #35
• #41

This package is not simple to install

... because we use an outdated rector version and also the pin on phpstan will prohibit any other version installed.
This is unfortunate and ideally we should upgrade to rector stable 1.x from our current 0.15.8 from april 23. The upgrade is not straight forward due to many breaking changes, which also happened in patch levels (they dont do semver) #56.
As discussed in the weekly our last resort would be to just bundle a phar and have that installed and at a later point totally refactor this package, removing all previous rules.

cc @kitsunet @dlubitz @ahaeslich

exchange `Neos.Fusion:RawArray` and `Neos.Fusion:Attributes` prototypes

These prototypes are not longer a part of neos after the Update to version 9

The correct prototype in this case would be Neos.Fusion:DataStructure as far as I found out

Renamed/Moved Classes are not detected in php

For example I got this exception while updating a project (DocsNeosIo) to Neos9:

Required class "Neos\ContentRepository\Migration\Transformations\AbstractTransformation" could not be loaded properly for reflection from "Neos\DocsNeosIo\ContentRepository\Transformations\UpdateHyphenTransformation"

And I know a fix for all classes will not be possible/overwhelming, but at least the most used ones should be fixed/commented by rector

Rector rule to discourage / warn about `path` usage in Fusion

NodeSearchService removed

In neos/neos-development-collection#4555 (comment) we removed the NodeSearchService. There was also a discussion about re-adding the Service, but was decided against: neos/neos-development-collection#3771

There are Upgrade instructions in the PR to migrate, but we should think about adding a comment or hint directly using rector.

Provide a migration for people using „sites“ and rewrite this to Neos.Neos:Sites?

We should provide a migration for people using „sites“ and rewrite this to Neos.Neos:Sites

Originally posted by @mhsdesign in neos/neos-development-collection#4339 (comment)

to be discussed in which places this should happen.

most obvious ones are in yaml configurations fx for startingPoints of the reference editor.

i think transforming php automagically might not be trivial, so I would count on manual migration there, but we should still highlight possible places with todo comments

some signals no longer exist

On the Neos Sprint in Hamburg I found out that some signals have been removed and replaced with catchUpHooks.

It would be pretty awesome if it would be possible to get a comment if the used signal is no longer supported
Maybe with a small hint for the hooks

Wip task migrate `NodeTypeConstraints`

... to be defined and discussed if deemed useful.

`ContentContext::getCurrentRenderingMode` to `RenderingModeService::findByCurrentUser`

- $renderingMode = $context->getCurrentRenderingMode();
+ $renderingMode = $this->renderingModeService->findByCurrentUser();

add Rector Fusion migration for @cache.entryIdentifier.[...] = ${node}