The right upgrade order is gold
As mentioned in the release blog post for Sulu 2.5.0 the order of upgrading Sulu to 2.5.0 should be:
- Upgrade your project to Symfony 5.4
- Upgrade your Project to PHP 8.0 / 8.1
- Upgrade your database to create the new schema for 2FA
- Fix any conflicting return types
- Optional but recommended: Replace usage of Swiftmailer with Symfony Mailer
- Now follow our Upgrading Sulu 2.x documentation to update your project to Sulu 2.5
- Optional but recommended: Update to Symfony 6
This sequence is highly recommended by us and you should try to do it step by step. Trying to do everything at once can be really frustrating and could end in chaos.
In the next steps I will show you how to achieve a successful update using Rector:
Step 0: Installing Rector and PHPStan
First we need to install Rector. As any dependency we install it via composer. Since Rector is built on top of PHPstan we also need to install this including its Symfony dependencies. If you have one or both tools already installed make sure you are updating them to the latest version and install the recommended extensions shown here:
The recommended way of configuring Phpstan is:
The Phpstan configuration requires two additional ".php" files which we need to create in our project. You can copy the following two code snippets to create them:
Step 1: Upgrading Symfony to 5.4
If you are already using Symfony 5.4 you can skip this. If not this is the important first step before you are updating something else.
This is part includes the most pitfalls and the most work as you are required to jump on a new major version of Symfony. But with Rector we are also trying to automate most things.
To update our code to be compatible with Symfony 5.4 we will first confiugre our
rector.php the following way. We are keeping the Rector file small so we can concentrate on the Symfony upgrade:
After configuring this you can run
vendor/bin/rector process to upgrade your code.
Now we need to adjust the composer.json and change all "symfony/" dependencies from "^4.4" to " ^5.4". With running
composer update all your Symfony dependencies should be updated to Symfony 5.4. Via
composer info command you can then check if all Symfony dependencies where updated correctly.
There are mainly 2 changes that effect typical Symfony projects when upgrading from 4.4 to 5.4. Depending on how successfully Rector was able to analyze your code some parts have been updated already.
The first one is that Symfony removed the "Symfony\Bundle\FrameworkBundle\Controller\Controller" class, which you need to replace with "Symfony\Bundle\FrameworkBundle\Controller\AbstractController". For this you need to define your services via the getSubscribedService method. Take a look at the official Symfony documentation here for details. A short example of the upgrade can look like this:
Secondly, there is the required update of your custom commands. Symfony removed the "Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand" class which need to be replaced with the "Symfony\Component\Console\Command\Command". Also if "autoconfigure" is not activated the command services need to be tagged with "console.command". Here's an example for this:
Now test your project if everything works like expected and eventually update other breaking changes of Symfony 4 - 5 update. Continue only after fixing all this additional incompatibilities to Symfony 5.4.
Step 2: Upgrading PHP to 8.1
If you are on PHP 8.0 or 8.1 already you can skip this step. Else we are now upgrading our code to be compatible with the latest PHP version. For this make sure you have PHP 8.1 installed on your System. Upgrade in your "composer.json" the "php" requirement to "8.1.*". If configured, the "config.platform.php" version to "8.1.8". After this change you should run "composer update" to update all your dependencies to a compatible PHP 8.1 version. In the next step we will update our PHP code to be compatible with PHP 8.1. We can achieve this via the following rector config:
After running the
vendor/bin/rector process command your code should be updated. Re-check all changes and eventually update them to your requirements.
Step 3: Upgrade Database schema
To upgrade your project database schema you can use manual migration via SQLs, just as documented in the UPGRADE.md. Alternative you can use the DoctrineMigrationBundle. Alternatively the recommended
bin/console doctrine:schema:update command to update the Schema of your database.
Step 4: Fix conflicting return types
Some return types has been changed from Sulu 2.4 to Sulu 2.5 so have a look at the list in the UPGRADE.md about this. The breaking changes here can again be updated via a Rector rule. We are now again adjusting our
rector.php to the following:
Step 5: Replace Swiftmailer with Symfony Mailer
This step is optional but recommend for future upgrades of your project. If you did use the Swiftmailer inside your project you should migrate all appeareance of it with the Symfony Mailer component. For this have a look at the official Symfony Mailer documentation.
Step 6: Upgrade Sulu to 2.5
In the next step you should upgrade Sulu to the latest 2.5 version by following the upgrade documentation. As documented the first step is to update the composer json via
composer require sulu/sulu:"~2.5.0" --no-update and
composer update command. Most skeleton changes are not required but if you want to keep your project with best practices have a look at the changes from 2.4.4 -> to 2.5.0 via Github.
If you run into any errors, check the UPGRADE.md file. If you are upgrading from a version before 2.4.x, you also need to follow the upgrade steps of the previous versions.
Step 7: Upgrade to Symfony 6.1
This step is optional but recommended. After you have upgraded successfully to Sulu 2.5 you should have no problem to upgrade your Project to Symfony 6 also. Here again Rector will help you by adjusting the rector.php file to the following:
After this you are on the latest version of supported dependencies of Sulu. I recommend now to update your
rector.php with the following configuration to activate the code quality checks of Rector:
In future upgrades adjust just your
rector.php to the desired version and Rector will do 90% of the work for you. Still, don't forget to follow the official upgrade docs and upgrade.md files of your dependencies.
With Rector and my recommended sequence we are keeping the update simple and focused on a single task. To me this is the most important when doing this upgrades.
Projects that keep Symfony and PHP up to date benefit here as they can simply skip the first 2 steps. And most of the work necessary will probably be doing the Symfony upgrade from 4.4 to 5.4.
As always, we are happy to hear your feedback about this new release of Sulu CMS.