Flow 7.2

This release of Flow comes with some great new features, bugfixes and a lot of modernisation of the existing code base.

As usual, we worked hard to keep this release as backwards compatible as possible but, since it’s a major release, some of the changes might require manual adjustments. So please make sure to carefully read the upgrade instructions below.

New Features

!!! FEATURE: Extensible configuration loaders

This PR allows to implement custom ConfigurationLoader classes which replace the currently rather hardcoded ConfigurationProcessor’s in an OOP way.

It is then possible to load custom configurations in the ConfigurationManager with custom locations and custom configuration formats. E.g. it is possible to load json files or NodeTypes from another directory than Configuration.

This is not a breaking change for most cases, but the signature of ConfigurationManager::registerConfigurationType() has been changed and the usage of “configurationProcessingTypes” deprecated in favor of Neos\\Flow\\Configuration\\Loader\\LoaderInterface instances:

// legacy (and still supported)
$configurationManager->registerConfigurationType('SomeCustom', ConfigurationManager::CONFIGURATION_PROCESSING_TYPE_APPEND);

// now
$configurationManager->registerConfigurationType('SomeCustom', new AppendLoader($yamlSource, 'SomeCustom'));

Related: https://github.com/neos/neos-development-collection/issues/3000

Related: https://github.com/neos/flow-development-collection/issues/1824

FEATURE: Preserve class and method doc blocks

This preserves the docblocks when generating proxies in order to not accidentially generate invalid annotations that break the classes.

See also #2387

FEATURE: Allow validation of dynamic argument types

This allows correct validation of action method arguments that are not statically typed, e.g. have a type hint of an interface. The type override via __type or the property mapping configuration will now take effect for building the correct validator chain, if the controller has the property $enableDynamicTypeValidation set to true.

If you enable this flag, note that the point in time when the validation chain is built is moved until after calling the initialize*Action method. This means that validator information is not available there any more.

Related issue: #1905

FEATURE: CLI parse array type controller arguments

With this PR, a CLI command can make use of array’s as an argument type.

If an argument is given multiple times and the type is an array, the argument values are pushed at the end of the array.

As an example, this can be handy, if you need to process multiple language dimensions, nodes or urls, like:

./flow my.pckg:index --dimension en --dimension de

Maybe this can also be considered for the 7.2 release?

The CLI RequestBuilder now distinguishes between array and non-array arguments. If an argument is of type array the argumentValue is appended to the array.

Create a command controller command with an array signature like:

public function indexCommand(array $dimension){

and then use the argument --dimension multiple times.

FEATURE: Update documentation for new configuration loader

I’ve added an updated documentation for the new configuration loader implemeted via https://github.com/neos/flow-development-collection/pull/2449

FEATURE: Support PHP8 attributes

This allows to use all existing Annotations as PHP8 Attributes and makes the ReflectionService pick up attributes like annotations. Hence all is*AnnotatedWith() and *Annotation() methods will return attribute classes as if they were annotations.

#[Flow\\Scope("singleton")]
class MyClass {

    /**
     * @var LoggerInterface
     */
    #[Flow\\Inject]
    protected $logger;

Note though, that this means a class that has both annotation and the equal attribute will behave as if all annotations were duplicated.

Also, in case you manually instanciated an Annotation class, you need to adjust to the changed constructor, which no longer takes a named array, but the list of actual properties. In most cases instead of new Flow\\Inject($args) you can probably do new Flow\\Inject(...$args) with PHP8 and named parameters.

For Doctrine Annotations - see https://github.com/doctrine/orm/pull/8266 which will be available with 2.9

FEATURE: I18n.translate() now accept $source to contain dots instead of only a path to the translation file

translateByExplicitlyPassedOrderedArguments() and I18n.translate() now accept $source argument to contain dots instead of only a path to the translation file.

When we use translations we use for example the shorthand:

{I18n.translate('Muensmedia.DistributionPackage:NodeTypes.Content.Todo.Container:ui.label')}

when we want to pass arguments we had to use:

${I18n.translate('progress', null, {solved: this.checkedElementsCount, total: this.checkboxCount}, 'NodeTypes/Content/Todo/Container', 'Muensmedia.DistributionPackage')}

As you can see, you have to pass the path to the translation file instead of the well known dot-notation.

This commit enables you to use also the well known dot-notation for the source argument:

${I18n.translate('progress', null, {solved: this.checkedElementsCount, total: this.checkboxCount}, 'NodeTypes.Content.Todo.Container', 'Muensmedia.DistributionPackage')}

In the method translateByShortHandString() we already replace dots with slashes, so I just copied this behavior to the method translateByExplicitlyPassedOrderedArguments() https://github.com/neos/flow-development-collection/blob/5b7b57523ab1a3b05105227e0a5266ece2777038/Neos.Flow/Classes/I18n/EelHelper/TranslationHelper.php#L140

Upgrade Instructions

This section contains instructions for upgrading your Flow 7.1 based applications to Flow 7.2.

In general just make sure to run the following commands:

To clear all file caches:

./flow flow:cache:flush --force

If you have additional cache backends configured, make sure to flush them too.

To apply core migrations:

./flow flow:core:migrate <Package-Key>

For every package you have control over (see Upgrading existing code below).

To validate/fix the database encoding, apply pending migrations and to (re)publish file resources:

./flow database:setcharset
./flow doctrine:migrate
./flow resource:publish

If you are upgrading from a lower version than 7.1, be sure to read the upgrade instructions from the previous Release Notes first.

Upgrading existing code

There have been major API changes in Flow 7.2 which require your code to be adjusted. As with earlier changes to Flow that required code changes on the user side we provide a code migration tool.

Given you have a Flow system with your (outdated) package in place you should run the following before attempting to fix anything by hand:

./flow core:migrate Acme.Demo

This will adjust the package code automatically and/or output further information. Read the output carefully and manually adjust the code if needed.

To see all the other helpful options this command provides, make sure to run:

./flow help core:migrate

Also make sure to read about the Potentially breaking changes below.

Inside core:migrate

The tool roughly works like this:

  • Collect all code migrations from packages

  • Collect all files from the specified package

  • For each migration

    • Check for clean git working copy (otherwise skip it)

    • Check if migration is needed (looks for Migration footers in commit messages)

    • Apply migration and commit the changes

Afterwards you probably get a list of warnings and notes from the migrations, check those to see if anything needs to be done manually.

Check the created commits and feel free to amend as needed, should things be missing or wrong. The only thing you must keep in place from the generated commits is the migration data in composer.json. It is used to detect if a migration has been applied already, so if you drop it, things might get out of hands in the future.

Potentially breaking changes

Flow 7.2 comes with some breaking changes and removes several deprecated functionalities, be sure to read the following changes and adjust your code respectively. For a full list of changes please refer to the change log.

!!! FEATURE: Extensible configuration loaders

This PR allows to implement custom ConfigurationLoader classes which replace the currently rather hardcoded ConfigurationProcessor’s in an OOP way.

It is then possible to load custom configurations in the ConfigurationManager with custom locations and custom configuration formats. E.g. it is possible to load json files or NodeTypes from another directory than Configuration.

This is not a breaking change for most cases, but the signature of ConfigurationManager::registerConfigurationType() has been changed and the usage of “configurationProcessingTypes” deprecated in favor of Neos\\Flow\\Configuration\\Loader\\LoaderInterface instances:

// legacy (and still supported)
$configurationManager->registerConfigurationType('SomeCustom', ConfigurationManager::CONFIGURATION_PROCESSING_TYPE_APPEND);

// now
$configurationManager->registerConfigurationType('SomeCustom', new AppendLoader($yamlSource, 'SomeCustom'));

Related: https://github.com/neos/neos-development-collection/issues/3000

Related: https://github.com/neos/flow-development-collection/issues/1824

!!! BUGFIX: Avoid broken proxy docblocks

With PR #2533 docblocks are copied from the original class to the proxy class. This breaks when using annotations without the “standard” imports Flow and ORM. One example is the ImportedAsset domain model.

This fixes that by some changes to the proxy building.

Note, if you use property introduction via AOP, those properties must from now on use fully-qualified classnames for annotations on them!

Example:

/**
 * @var string
 * @Doctrine\ORM\Mapping\Id
 * @Doctrine\ORM\Mapping\Column(length=40)
 * @Flow\Introduce("Neos\Flow\Persistence\Aspect\PersistenceMagicAspect->isEntityOrValueObject && filter(Neos\Flow\Persistence\Doctrine\Mapping\Driver\FlowAnnotationDriver)")
 */
protected $Persistence_Object_Identifier;