Neos and Flow 9 - a Foundation for the Future
Neos 9 comes with the biggest technical overhaul since we reworked the editing UI in React: the Event Sourced Content Repository. The Content Repository is the heart of Neos, it stores all your content, its properties, its relations, all your dimensions and now also a complete history of the changes that were made to it.
We have worked on the concepts that are now the Event Sourced Content Repository since 2016. We reviewed, reworked and refined them again and again, building on what we learned from projects large and small.
The Neos and Flow 9.0 release is not the finish line. It is the kickoff for the next decade of content management in Neos. Our vision for features that are a technical possibility now include comprehensive undo for editors, a content repository for assets, performance improvements and even ideas about true collaborative editing in Neos.
As with every X.0 release of Neos and Flow there will be rough edges that we will continually improve. We provide recommendations for how to start using Neos 9 and updating your existing projects in this article. We encourage all developers to start getting to know the new concepts and features in Neos 9 by reading the documentation and starting new projects with Neos 9 now.
Neos 9 Release Highlights
General Improvements
Scalability - with the new Event Sourced Content Repository Neos can handle much more content than before. Your website has hundreds of thousands of content elements? Let Neos handle them! We are looking forward to test the limits of our new Content Repository in huge projects.
Update-ability - as with every previous Neos release we strive to make the update as easy as possible. Even though Neos 9 brings a completely new way to manage your content internally, we provide automated update scripts and comprehensive update instructions for those cases that must be decided individually.
Audit Trail - as soon as you start using Neos 9 your content has an audit trail. Every change to it is automatically recorded in the system. A following feature release will provide a user interface to view this audit trail.
Performance - the new architecture of Neos 9 unlocks new performance that was only possible with a two-stack approach before. The Neos 9 release brings this lightning fast performance to routing. As Neos 9 is essentially a two-stack architecture in itself, it will only get faster from here.
System Requirements - new release new hardware requirements? Not with Neos and Flow! Yes, Neos and Flow 9 require current versions of PHP and your database engine, but your Neos and Flow 8 server can handle Neos and Flow 9 just as well.
The Neos login page now allows the display of image attribution.
For Editors
While the true potential of Neos 9 will be unlocked in future feature releases, editors profit from the following new features and possibilities today.
The publishing workflow is much smarter with Neos 9. The new publishing updates individual properties instead of overwriting the whole page. This is especially useful if multiple editors work on the same page. Additional integrity checks have been added that prevent loss of content. Publishing a new page without its new parent page and complex move operations will detect the problems beforehand. "Orphaned nodes" as we called them, are no longer possible!
Properties of content can now be shared across dimensions. This can save editors a lot of time. If the address of your retail store is the same in every language dimension of your website you can now configure that and only have to update the information in one language afterwards. No more changing the exact same data in multiple languages!
Links from one content element to another are now aware of both directions. How many articles in your news archive are tagged with "press release"? With Neos 9 the "press release" tag knows to which articles it was applied, making it much easier to display count information and answer questions that start with "How many...?"
Font Awesome 6 is now part of Neos 9. This means hundreds of new icons can be made available to editors in the Neos Backend to better distinguish types of pages, types of content and many other UI elements of the Neos backend. You missed a worm, mountain-sun, sailboat or glass-water icon? Despair no more, they are here with Neos 9!
CKEditor - the rich text input for your content in the Neos Backend - has been updated to the current version. The editor provides an improved experience with better performance and fewer bugs.
The Workspace Module of Neos 9 is based on the package by Sebastian Helzle and brings many new features: a hierarchical view of workspaces, access control, a better overview of changes in a workspace and it displays when content in a workspace was last changed and by whom. And it's our first HTMX based backend module and won't be the last.
For Developers
Event Sourced Content Repository
The Event Sourced Content Repository comes with new concepts for developers to learn. We have created documentation to help experienced and new Neos developers get a quick start. A glossary gives an overview and explanation of new terms we use in Neos 9.
The biggest change is the separation of the read and write APIs for the Content Repository according to CQRS (Command Query Responsibility Separation). Both sides are strictly typed providing IDE support for content graph and command operations. Core concepts that changed with the new Event Sourced Content Repository are: nodes, node relations, subgraphs, dimensions, content graphs, workspaces and the content repository. A glossary was created to explain terms and concepts.
The Event Sourced Content Repository records all events that change content. Thus a granular Audit Trail is created in the database.
Neos 9 allows the usage of multiple instances of Content Repositories enabling different dimension configurations in each repository.
The Event Sourced Content Repository was developed so it can be used standalone. The core of Neos is now available to be used by itself without Neos. You need a flexible, extremely well test-covered and testable, content storage that supports dimensions and workspaces and that is open source? Look no further and give our Content Repository a try!
Extensibility
Node signals are gone. The new Content Repository is extended through the CommandHookInterface and Projections.
The CommandHookInterface allows you to hook into the write side API of the Content Repository. See commands before they are applied. This gives developers the possibility to change them and also to create additional commands after handling the original command.
Projections are the read side API of the Content Repository. Register a projection for an event, to update/recalculate certain data when new events are observed in the content repository. This optimizes read performance as calculations are not performed during requests but when the (data-) change event was processed.
Changes to Nodes
With Neos 9 Node properties can be scoped. Options are scoping to
- the node aggregate - the node in every dimension or
- specializations - for example only to all sub-variants of English and not to other languages
The content graph which is the backbone of the new Content Repository allows much easier evaluation of back references. Answering the question "Which nodes are pointing to this node?" was hard before Neos 9. In many projects Elasticsearch was used to get these information reliably and fast. This is not necessary any more. The new Content Repository knows which nodes point to my node.
Fusion
There are breaking changes in Fusion - review the upgrade documentation to read about them. We provide rector migration instructions to convert your existing code.
Neos.UI Updates
CKEditor Major Update
CKEditor was updated from version 16 to 44. Your plugins are very very likely to need adjustment to the new API. On the upside, you can now use all the features of the current CKEditor version.
MoveNodeStrategy
A new configuration option was added to define how a node behaves when moved. The documentation can be found in the code.
'Your.Package:NodeType':
options:
moveNodeStrategy: gatherAllyourNodeType.yaml
Flow 9 Release Highlights
Flow 9 brings technical improvements that are the framework for Neos 9 and make it fit for future development. As with Neos, we carefully worked on many details to create a solid foundation for modern PHP applications.
PSR-7 Compatibility and Controller Interface Improvements
Flow 9 embraces modern PHP standards with a completely redesigned controller interface. Gone are the days of managing mutable response objects throughout your application. Instead, controllers now follow a clean, functional pattern that directly returns PSR-7 responses:
interface ControllerInterface
{
public function processRequest(ActionRequest $request): ResponseInterface;
}
This shift to PSR-7 compatibility extends to views as well, which now return StreamInterface objects. Your controllers can be more elegant and expressive:
public function myAction(): ResponseInterface
{
return (new Response(status: 200, body: $output))
->withAddedHeader('X-My-Header', 'foo');
}These changes not only create a cleaner architecture but also improve interoperability with the wider PHP ecosystem, making Flow applications more maintainable and future-proof.
Modernized Data Persistence with Doctrine DBAL 3
Flow 9 upgrades to Doctrine DBAL 3, bringing modern data handling capabilities to your applications. This update introduces smarter JSON handling, replaces legacy cache implementations with PSR-6 compatible alternatives, and streamlines data access. These improvements work behind the scenes to boost your application's performance and reliability, all while maintaining compatibility with your existing code.
Ready for the Future with PHP 8.3 and 8.4
We future-proofed Flow 9 with comprehensive support for the latest PHP versions. The framework has been carefully optimized to eliminate deprecation warnings and leverage the performance improvements in PHP 8.3 and 8.4. We also dropped a lot of code which was only there to support PHP 7.4 and earlier.
We streamlined Flow's proxy class building and reflection system, eliminating complex legacy code and removing the outdated package freezing concept. These changes result in more consistent behavior across all application contexts and a leaner, more maintainable code base.
Performance that Scales
Performance matters, and Flow 9 delivers with targeted optimizations throughout the framework. Redis cache operations are now faster and more efficient, resource loading has been refined to eliminate redundancies, and we removed race conditions that impacted application reliability in rare cases.
The routing system has been decoupled from the persistence manager, providing significant performance gains, especially for applications with complex route configurations. These improvements work together to make Flow 9 applications more responsive and capable of handling increased loads.
The session handling of flow has been optimized and modernized. Now the session data is only updated after updateMetadataThreshold as long as no content changed. This reduces the number of session cache writes and significantly.
Improved Error Handling and Validation
We enhanced Flow's error handling to be more intuitive and informative. Critical errors now properly report HTTP status code 500 instead of misleadingly returning 200. Validation functionality, particularly for file uploads, provides clearer error messages. Database queries with complex relationships now correctly count results, and date handling in validators is more robust.
These changes mean fewer debugging headaches and more reliable applications, whether running in a web environment or via the command line.
Upgrade Strategies to Neos and Flow 9.0
We recommend to use Neos 9.0 for new projects.
Upgrading Small Websites
If you run a small website that only has very little PHP the chances are good that upgrading to Neos 9.0 is easy. Follow the instructions and enjoy the benefits.
Upgrading Large Websites or Projects with a lot of PHP
Upgrading large projects to Neos 9.0 is currently still more complex than we would like. Our recommended upgrade strategy is to wait for Neos 8.4 which will provide preparations for large projects to make the upgrade easier. As we said in the past: if you work on an upgrade of a large project from Neos 8.3 to Neos 9.0 and you encounter problems, you can reach out to service providers that provide core development services.
Updating Packages to Neos 9.0 compatibility
100 packages are already flagged as compatible with Neos 9.0. If you encounter a package that is not, contact the package maintainer to update their package. You can reach out to service providers that provide core development services if you want to hire help.
Documentation and Upgrade Instructions
Documentation
The Neos documentation has been updated and extended to explain the new concepts of the Event Sourced Content Repository.
An FAQ document explains our reasoning for architecture decisions that changed in Neos and Flow 9.
Change Logs
For the full list of changes, please refer to the release notes
- Neos - https://github.com/neos/neos-development-collection/releases/tag/9.0.0
- Neos.Ui - https://github.com/neos/neos-ui/releases/tag/9.0.0
- Flow - https://github.com/neos/flow-development-collection/releases/tag/9.0.0
Upgrade instructions
For the full upgrade instructions, please refer to: Upgrade Instructions 8.3 → 9.0
See the release notes for further information: Flow 9.0 Release Notes, Neos 9.0 Release Notes
Contributors
Special thank you to our release team for Neos and Flow 9.0: Anke Häslich, Bernhard Schmitt, Christian Müller, Marc Henry Schultz and Sebastian Kurfürst.
We also appreciate everyone who contributed to the Friday weeklies — especially Denny Lubitz, Bastian Waidelich, and Paula Kallert — your dedication made a real difference.
Thank you to all financial supporters of the Neos Project - these contributions made the rewrite possible.
Contributors to the release: