Upgrade Instructions
You don't care about the exciting new changes, but just want to get up and running with the latest release? Here are the upgrade instructions from Neos 3.3 to Neos 4.0.
React UI
With Neos 4.0 the React UI Backend is now the default when editors login to Neos. To learn about the great ways the new backend can be extended watch the talk from Dmitri Pisarev and Max Strübing given at Neos Conference 2018.
We continue to improve the performance and stability of the React UI as we get more and more feedback from projects. If you stumble across a bug, check the list of existing issues on Github and submit a new one if you your bug is not listed.
Emojis!
Emojis can finally be used in Neos now. What kept us back so far was our default database collation and character set utf8. With Neos 4.0, the new default will be utf8mb4. This allows us to store emojis (and other 4-byte UTF characters) in the database and provides our editors with fun new ways to mark up their content.
External Asset Sources
Another highlight that has landed in Neos 4.0 is the integration of external asset sources. An asset source is a connector between the Neos Media module and a third party asset management service. This could be services like Google Drive or Dropbox, but also specialized asset management tools like Elvis DAM. Access to the actual assets is done via Asset Proxy objects, which encapsulate the access to the asset itself. We suggest watching Robert's NeosCon talk "Everything about Assets" - you can skip directly to minute 25 to see the new features.
The new API is used by the Neos core, but the public API is likely to evolve quite a bit and therefore is considered beta-quality. If you plan to use asset sources in your projects, keep an eye on the change logs in the next versions of Neos.
Changes in Neos
FontAwesome upgraded to version 5
The icon library which we use to define icons for node types has been upgraded to version 5. This gives you access to a whole lot of new icons for your Neos backend.
New document rendering best practice
For quite some time, when you wanted to render different document types differently you had to add an entry to the root matcher in Fusion and render a different Fusion path. A year ago, we started recommending a new best practice based on Fusion prototypes, similar to the way content types are rendered. This best practice has now found its way to the core. By simply defining a Fusion prototype whose name matches the document node types, you can now render pages differently. The documentation on page rendering has been updated to reflect the new best practice.
This change is potentially breaking - if you have Fusion prototypes which have the same name as your document node types, make sure to double-check that everything is rendered correctly.
New "CanRender" Fusion Object
Because of the change above, a new Fusion object was needed in the core. Neos.Fusion:CanRender allows you to check if a Fusion prototype can be rendered (is available). We expect this to be quite useful for planned extensibility of packages, which is its purpose in the Neos core. Check the Fusion reference to see an usage example.
Fusion Namespace changes
Namespaces were previously transported over include boundaries and thus could end up being declared differently in different packages. This was a convenience feature, which however could easily lead to confusion.
Starting with Neos 4.0, namespaces are now handled like in PHP and are only valid for the Fusion file they are declared in. There is a core migration to adapt existing code, so make sure to follow the upgrade guide.
New "remove" FlowQuery Operation
There is now an operation to remove a node or a set of nodes from a FlowQuery context.
DateTime from String in Eel
You can now directly create new DateTime objects in Eel by calling e.g. Date.create('yesterday'). The string will be passed to the DateTime constructor directly.
Changes in Flow
PHP 7.1 requirement
Flow, and therefore Neos, now require PHP 7.1 as a minimum version.
MySQL and MariaDB requirement change
If you are using a MySQL based database you must use at least MySQL 5.7.x or MariaDB 10.2.x.
Other database systems are not affected.
PSR-3 logging
The logging functionality in Flow now implements the official PSR-3 logging interface, therefore making it more standards-compliant and reusable.
PSR-6 and PSR-16 support for caching framework
Flow now provides PSR-6 compatible cache factories and a PSR-16 compatible SimpleCache implementation. These are not used in the Flow core yet, so the Flow CLI command will not flush them as of now. If you use these cache objects, you need to take care of flushing them yourself.
PSR-11 Object Management
With just 22 lines of code, our ObjectManager has been turned into a PSR-11 compatible dependency injection container. We will continue to adopt PSR standards as soon as possible, thereby opening up parts of Neos and Flow to use outside of the respective frameworks.
utf8mb4 is new default database charset and collation
As described above, we now set databases to utf8mb4 by default in order to handle emojis and other 4-byte characters correctly.
Split Source for Settings.yaml
Similar to the way NodeTypes can be split across different files, you can now have multiple different files for Settings-type configuration. This means that files like Settings.xyz.yaml or Settings.MyStuff.yaml will be parsed and loaded, giving you more options to structure your packages.
Support for the "Forwarded" HTTP header
Flow now supports the standardized "Forwarded" HTTP header, described in RFC 7239 Section 4.
Package Management cleanups / deprecations
There has been some cleanup done in package management. Packages now no longer have state, they are either available or not available entirely depending on the fact if they are installed via composer. This means that the package:activate, package:deactivate and package:delete commands are removed. The implemented PackageManager still supports the getActivePackages and isPackageActive methods for backwards compatibility but both are deprecated and removed from the interface. The infamous PackageStates.php file is moved to Data/Temporary, effectively becoming a transient cache. No more rm Configuration/PackageStates.php! Also, there is now a low-level split between Flow and non-Flow packages - meaning we no longer will (try to) load configuration from non-Flow packages.
CLI globbing
You can now use the asterisk "*" as an argument for the following CLI commands to target all objects:
- site:prune
- site:activate
- site:deactivate
- domain:delete
- domain:activate
- domain:deactivate
- user:delete
- user:activate
- user:deactivate
- user:addrole
- user:removerole
Fluid updated to 2.5.x
Our template engine Fluid has been updated from 2.1.x to the 2.5 branch, bringing you the newest features and fixes from the Fluid core.
Documentation and Support
Upgrading
The detailed upgrading process for Neos 4.0 is explained in the upgrade instructions.
Changelogs
See the Neos 4.0 changelogs and Flow 5.0 changelogs for all changes and details.
Support for Neos 4.0 and Flow 5.0
As shown in our release roadmap, Neos 4.0 and Flow 5.0 will get bugfixes until December 2019 and security fixes until December 2020.
Get Involved!
This release is the product of a great community! Join the conversation at discuss.neos.io or on Slack and be part of our community and help us build the next release of Neos. If you are considering Neos for your organization, but have some unanswered questions, please feel free to get in touch with the Neos Team. We would be happy to help you get started on your Neos journey!
And if Neos helps you with your business, how about supporting the Neos Team financially, so we can meet in person and work on the next releases?
Neos Conference 2019
From May 10th to 11th 2019 - the Neos Community gathers at the Neos Conference in Dresden, Germany. Join us to meet the "who-is-who" of the international Neos community: team members, agencies and organizations, developers and maybe future colleagues.