Neos 9 Beta-17 Release

Announcements
1

Today we released another Neos 9 Beta.

Because it doesn’t snow here, have a special snowflake in form of a new shiny Beta ︎❇︎

Thanks to all who contributed <3.

Upgrade instructions from Beta 16

previous beta → Neos 9 Beta-16 Release

In your composer.json you should require 9.0.0-beta17 for all Neos packages from the development distribution and for the NeosUi as well as Flow:

"neos/flow": "9.0.0-beta17",
"neos/neos": "9.0.0-beta17",
"neos/neos-ui": "9.0.0-beta17"

The database can be migrated the following way:

A setup to apply the latest schema adjustments:

./flow doctrine:migrate
# special schema migration see below:
./flow migrateevents:migratecheckpointstosubscriptions
./flow cr:setup

Additionally, PRs marked with :boom:⛁ need a dedicated migration

  • :boom:⛁¹ Migration to move projection’s position to subscription table

This migration which is rather a schema adjustment, should be carried out directly and requires NO replay.

./flow migrateevents:migratecheckpointstosubscriptions

Contraire to its name, it does not migrate events. If its not run the schemas dont match and the following error is thrown:

An exception occurred while executing a query: SQLSTATE[42S02]: Base table or view not found: 1146 Table ‘database.cr_default_subscriptions’ doesn’t exist

  • :warning:Note to publish all legacy copy’s to live

As said in the last beta, please note that copy nodes was refactored.
In case you’re running on a project with events from before Beta16 the legacy copy nodes events must be published to the live workspace before the final release of Neos 9.
To detect those cases please use:

./flow migrateevents:copynodesstatus

Features

1.) !!! CKEditor update to version 44

This update represents a major leap forward, spanning several years of development. Due to the extensive changes and numerous breaking changes, it’s challenging to provide a comprehensive list of all API alterations. As such, this PR introduces a breaking change.

The CKEditor API has evolved significantly, and any plugins relying on outdated APIs may no longer function as expected. We cannot provide a detailed upgrade guide for your custom or third-party plugins. Instead, we recommend consulting the release notes of CKEditor 5 for the relevant versions. Note that during testing, some packages dependent on the old implementation were found incompatible.

To support the community, we aim to review a few community plugins and, where feasible, submit PRs to update them, offering practical examples.

This upgrade effort has been attempted multiple times over the years, but often proved too challenging to complete.
We want to acknowledge and thank all who contributed to earlier effort addressing this task.

See also: Feedback needed: In which release to include CKEditor 5 Update

2.) :sparkle:︎ Highlight :sparkle:︎ Overhauled catchup of projections

This refactoring introduces a subscription engine to manage the projections which is inspired by patchlevel.

Projections are now understood as abstract concept of subscribers. Active subscriber will be invoked (catch upped) for each new event. The subscription tracks their position and also their state.
At the beginning subscriptions are NEW and via ./flow cr:setup marked BOOTING. Via ./flow subscription:replay the subscriber will then process all events and later be set to ACTIVE.

Previously the catch-up was implemented via the means of dedicated checkpoint tables.
The new approach allows for a more control (e.g. only active subscriptions are catch upped during runtime - not newly installed like before) and the concept provides a well foundation for possible other subscribers in the future and tracking those.

The command ./flow cr:status was enriched with information containing now information about a subscribers position and their state.

Further the change introduced new cli commands for further managing subscriptions see ./flow subscription --help

  • ./flow cr:projectionreplayall will be replaced with ./flow subscription:replayall
  • ./flow cr:projectionReplay will be replaced with ./flow subscription:replay

The subscription:replay will take as argument the subscription id as shown in ./flow cr:status, for example to replay the content graph projection run: ./flow subscription:replay contentGraph

Catch-up Hooks

The hook CatchUpHookInterface::onBeforeCatchUp receives a parameter $subscriptionStatus.
During “normal” runtime this is ACTIVE but for a replay this is set to BOOTING allowing catchup hooks to behave differently - e.g. disable themselves.

The hook CatchUpHookInterface::onBeforeBatchCompleted was replaced with CatchUpHookInterface::onAfterBatchCompleted.
Previously batching during the catchup was not leveraged, so technically onBeforeBatchCompleted was equal to onAfterEvent.
The hook onAfterBatchCompleted differs that it is run after the projection is persisted.

Also, the error behaviour was changed that a catchup hook will not crash the projection. Its assumed that the hooks are stable and generally don’t throw.
If a hook fails still its error will be caught and rethrown at the end after the catchup is fully finished.

PHP API - The ContentRepositoryMaintainer

The content repository does not expose ContentRepository::setUp any longer.
Please use the maintainer to set up and manage a content repository.

The maintainer can be retrieved as a content repository service:

$contentRepositoryMaintainer = $this->contentRepositoryRegistry->buildService(
    $contentRepositoryId,
    new ContentRepositoryMaintainerFactory()
);

Initialisation / Tear down

The method setUp sets up the content repository like event store and subscription database tables.
It is non-destructive.

Resetting a content repository with prune method will purge the event stream and reset all subscription states.

Status information

The status of the content repository e.g. if a setup is required or if all subscriptions are active and their position
can be examined with status

The event store status is available via ContentRepositoryStatus::$eventStoreStatus, and the subscription status
via ContentRepositoryStatus::$subscriptionStatus. Further documentation in SubscriptionStatusCollection.

Subscriptions (mainly projections)

This maintainer offers also the public API to interact with the subscription catchup. In the happy path,
no interaction is necessary, as ContentRepository::handle() triggers the subscriptions after applying the events.

Special cases:

Replay for initialisation

For initialising on a new database - which contains events already - a replay will make sure that the subscriptions
are emptied and reapply the events. This can be triggered via replaySubscription or replayAllSubscriptions

And after registering a new subscription a setup as well as a replay of this subscription is also required.

Replay to repair

In case a subscription is detached and then reinstalled a replay will make sure its caught up to all new events.
And that the previous state will be reset as the projections logic might have changed.

Also in case a subscription runs into the error status, its code needs to be fixed, and it can be attempted to be replayed.

3.) Simplified dimension (publishing) behaviour

This beta attempts to fix several problems that we found regarding publishing and dimensions in the Neos Ui.
While some changes are slightly bold they allow to tighten the feature set to a working and tested one.

Summarized changes for the Neos Ui user:

  • the user interface will not allow copy node across dimensions as behaviour has yet to be (re)-defined
  • content elements will be moved only in the current dimension, while content is generally moved across all dimension (configured via options.moveNodeStrategy)
    • the move is marked in all affected dimensions
  • if a change is not publishable - e.g. publish a child document before its parent, an exception is thrown instead of a misleading dialog (this will yet be improved again)
  • publishing will NOT distinct between dimensions like in Neos 8.3 where only the currently selected dimension is published - the document is published in dimensions instead

Bugfixes

Neos

Dev only relevant

List of things

Neos

Neos Ui

3 Likes