Upgrade Neos from 2.1.2 to 8.3

Due tue the ending basic support for projects below PHP version 8.1 on Mittwald, I’m looking for a way to upgrade Neos to the latest version. I have created this project around 2015 on a voluntary basis for my sports club. Neos 2.1.2 has been running smoothly for all these years and has never been upgraded.

Is there a recommended way to perform this upgrade?
I have checked the upgrade instructions from the documentation. Do I need to upgrade to every minor release one at a time, or is there a faster way?
Or would it be easier to start over with a fresh installation of Neos 8.3 and try to rebuild the project there?

Thank you very much for your help

Hi @Daniel_Oliver

Welcome to the forum. I’ve done this before and I suggest to take these steps:

  • 2.3 to 3.0, in version 3.0, the resource management had breaking changes, also, the namespace was changed to neos/. The upgrade guide will help you through all migrations.
  • 3.0 to 4.0 will bring you the formerly new Neos UI.

As far as I remember, you can then go straight up to Neos 8.3 as long as you apply all core, node and Doctrine migrations and migrate breaking changes not covered by the migrations. So you don’t need to upgrade to each version, but take into account the breaking changes in all upgrade guides inbetween. I’d like to point out the removal of the prototype generators in 5.0 which will most likely require some manual work.

Without seeing the project, it’s hard to tell if starting over is easier for your project. If you start over, you will most likely use new best practises, e.g. Fusion AFX instead of Fluid templates. This will be better going into the future, but take more time. Templating with Fluid is still possible in current Neos versions, so if you just want to get the job done as quick as possible, you better upgrade.

Hi @lorenzulrich,

thank you very much for your reply, I will try to do the upgrade like you described.

One question. When I first created the project I didn’t know better and defined some of my Node Types within the Neos core packages, instead of my own project. Of course the NodeTypes.yaml is overwritten on every update. Is there a simple way to migrate these Node Types to my project, meaning I just move them to the other yaml, or do I need to do some kind of database migration when doing this?

Thank you very much again

Just move them to a yaml inside your own site, the contents of all NodeTypes.yamls are merged anyways. :slight_smile:


I have started with the upgrade from 2.1 to 2.2, as shown in the upgrade instructions, but I’m already failing.

Highlited notices during composer upate:

The “neos/composer-plugin” plugin requires composer-plugin-api 1.0.0, this WILL break in the future and it should be fixed ASAP (require ^1.0 for example).

Warning from https://packagist.org: Support for Composer 1 is deprecated and some packages will not be available. You should upgrade to Composer 2. See https://blog.packagist.com/deprecating-composer-1-su pport/

After the update I’m getting “HTTP ERROR 500” loading the frontend.

The only Exception within System.log:
24-03-12 23:13:24 535045 CRITICAL Flow Exception in line 109 of /html/neos/Packages/Framework/TYPO3.Flow/Classes/TYPO3/Flow/Core/Bootstrap.php: Call to undefined method TYPO3\Flow\Http\Component\ComponentChain::getResponse() - See also: 2024031223132455bfe8.txt

PHP version: 5.6

composer.json I have used for the update:

Any hint would be greatly appreciated :slight_smile:

I suggest to use the package versions of the Neos packages as per the Neos Base Distribution of the respective version. This helps you building a working installation.

Personally, I’ve only made sure that the Flow CLI works on the intermediate steps, so you can execute Core and Doctrine migrations. I did not try to have the frontend running because I didn’t want to waste time.

You will also need to delete Web/index.php when going from 2 to 3 as far as I remember. It will be regenerated with a composer update.

Starting with Neos 4, I would switch to Composer version 2.

Thank you Lorenz, I will try it again with the original composer.json from version 2.2.

Unfortunately the frontend needs to keep running without much downtime, because we don’t have a development system and the website needs to be available. Maybe it would be better to create a clone of the environment on my local machine, where I can work without time pressure and without the need to restore backups. The docker installation does not really work for me, so I will try to install a local webserver + database and copy all of the files from the SFTP. Or do you know a better way of cloning the system?

Thanks again

@Daniel_Oliver Oh, I wasn’t aware you wanted to update the live system. I’d strongly suggest not to do that. We are using DDEV which is based on Docker. No need to setup PHP und co. locally and having multiple versions in parallel, you just change the version in the config file and restart DDEV. It may not be the fastest alternative, but for such a project, I think it’s a great thing.

1 Like

I you NOT want to do this upgrade live. Get a development setup, it’s waaaay too old a version that this will go fast and smooth.

1 Like

Hi @lorenzulrich and @christianm,

thank you for the hints. It took me a few days, but I was abe to ge ddev up and running. I also managed to update Neos from version 2.1 up to version 2.3.

I’m currently struggeling with the update to version 3.0. There seems to be an issue with the package “neos/behat”. Error message:
Source directory Packages/Application/Flowpack.Behat/ has unpushed changes on the current branch:

  • M composer.json*

I have tried both the composer.json config from version 3.0, as well as the patched composer.json changed by “./DistributionUpgrader.phar”. Tried versions: 3.0.0, 4.0.x-dev, 4.0.1.

Is there a way I can get this package to work?

Thanks again

Sounds like someone changed said file Packages/Application/Flowpack.Behat/composer.json this file shouldn’t be changed at all, if nothing else helps you could just delete the whole Flowpack.Behat folder and let composer install the new version.

What @christianm says is always a good idea: If any external dependency makes you problems, just delete the code and run Composer again. Saves you time.

If it still doesn’t work with Behat, just remove the package. You don’t need it for running a website, it is just used to run the test suite.

Btw its now Neos.Behat and no longer in FlowPack i would suggest to look at the composer.json of an up to date neos distribution neos-base-distribution/composer.json at eb709befbd85dab93af7a9edcf0b4e6dbdb8e0dc · neos/neos-base-distribution · GitHub

and use this as a template and add your additional dependencies back into it.

Hi all,

thank you for your input so far. After removing the Behat package I was able to run the composer update and update to 3.0, following the upgrade guide. Unfortunateley this upgrade completely broke flow and I’m not able to run it. Error message for calling “./flow”:

As a hobby web developer, I feel like this upgrade is way to complex for me. Fixing a problem will result in other problems. And I’m not even close to the latest version yet. Maybe it would be easier for me to start from scratch with a fresh installation of 8.3. Also looking at all the changes that happened within the last 8 years.

From your experience: Do you see a way to reuse parts of the database, so we don’t have to manually enter all of the data again? Is there also a way to migrate Node Types within the database, should they change in the new project?