Upgrade Instructions 8.3 → 8.4

By using composer, you can update an existing installation to a specific version, without having to create a new project.

For further information on what changed, please take a look at the changelogs (Neos, Flow)

#Update Instructions

Before making substantial changes, make sure you create a backup of the database and files!

bash
cd /installation-root/
# Update the core package dependencies
composer require --no-update "neos/neos:~8.4.0"
composer require --no-update "neos/neos-ui:~8.4.0"

# Update optional package dependencies (if installed)
composer require --no-update "neos/demo:~8.4.0"

If you have development packages in your composer manifest, update them to match as well:

bash
# Update development packages (if installed)
composer require --no-update --dev "neos/buildessentials:~8.4.0"

Make sure to update every required neos package to ~8.4.0! Otherwise there can be an error during updating, because of version conflicts.

#Breaking changes

With this minor release, no breaking changes were introduced. But a few defaults changed to align to the upcoming Neos 9.0 behaviour. These settings allow you to restore the 8.3 behaviour:

yaml

# This feature flag changes the preview link button in the backend to operate more in the sense of a preview for
# how the current workspace would look like when published. Before it would show the page in the parent workspace,
# but without changes applied. The new behavior in combination with preview modes allows seeing what a page might
# look like after publishing it. The drawback is that for example the live URL is no longer visible as the preview
# never shows the Live workspace. Also editors might be confused by the different behavior.
# With Neos 8.4 it is enabled by default and can be reset to enable the 8.3 behaviour. Starting with Neos 9.0 the behaviour changes fully to the new one.

Neos:
  Neos:
    Ui:
      nextVersionPreviewBehavior: false


# The options "Import a site" and "Create a new site-package" are hidden by default in Neos 8.4
# the functionality is removed via Neos 9.0 but can be restored by settings

Neos:
  Neos:
    modules:
      administration:
        submodules:
          sites:
            settings:
              enableLegacyPackageImport: true
              enableLegacyPackageCreation: true

#Finish the update

bash
# Update the packages
composer update

# Flush the caches
./flow flow:cache:flush --force
./flow flow:session:destroyAll

# Run code migrations, as needed for any packages that need to be
# migrated. Rule of thumb:
#
# - any 3rd party packages that still install fine at least claim
#   to work, and should be updated by their maintainer(s).
# - your own packages should always be treated with a migration,
#   at least it marks that as done.
#
./flow flow:core:migrate <Vendor.PackageName>

# Run database migrations
./flow doctrine:migrate

# Publish resources
./flow resource:publish

Note that the new core migration 20251006080506 handles the migration of the legacy Fusion prototypes like Neos.Fusion:Array. If the migration needs manual adjustment, like to rename collection to items, a warning is shown and also a "todo"-comment following the pattern TODO Neos.Fusion-20251006080506 is added to the top of the file.

Fusion Core Migrations CLI

Migration to rename all legacy Fusion prototypes

#Prepare Fusion for Neos 9.0

With the Neos 8.4 release some of the new Neos 9.0 Node APIs and EEL helper were back-ported. So we prepared some of the Fusion migrations for 8.4 already to make them available already for early adopters.

As they are optional these migrations are not part of the regular core migrations (./flow flow:core:migrate).

Instead the adjustments can be run manually via flow command. Ambiguous cases like "aPossibleNode.identifier" are ignored and not rewritten. It is safe to rerun this migration and also to run the upcoming 9.0 migration via "flow:core:migrate" when actually updating.

Be aware that the migrated code is only compatible with Neos 8.4 and upwards and cannot run with Neos 8.3 any longer. Also this is merely a preparation and not all cases can be migrated in Neos 8.3 as some changes require more features from Neos 9.0. When you finally upgrade to Neos 9 at some point, some further changes might be necessary.

bash
./flow neos9preparation:preadjustfusion <Vendor.Package>

#Troubleshooting

If you run into trouble with Neos content or resources, the following may help: 

bash
# If you get error messages when running Flow CLI commands:
rm -rf Data/Temporary

# If you experience issues with pages not working, try 
./flow node:repair

# If you experience issues with resources, thumbnail or assets, try
./flow resource:clean
./flow media:clearthumbnails
Upgrade Instructions 8.2 → 8.3