Upgrading Sulu 2.x¶
This upgrade guide describes how to upgrade a Sulu 2.x project to any newer version below 3.0. In a majority of cases, these upgrades should be unproblematic, because backwards compatibility is only broken when it is really necessary to fix a bug. The upgrade process consists of the following steps:
1. Update the sulu/sulu package¶
The sulu/sulu
package implements the functionality of the Sulu content management system. To update this package, you need to update the version constraint for the package in the composer.json
of your project.
To do this, you can replace the ~x.x.x
with the a version constraint like ~2.2.7
and execute the following
command in the root folder of your project:
composer require sulu/sulu:"~x.x.x" --no-update
After this, you can update all dependencies of your project by executing the following command:
composer update
Note
See the Composer documentation for more information about version constraints.
2. Check sulu/skeleton repository changes¶
The sulu/skeleton repository contains the project template for Sulu projects. The template might be adjusted
between different versions to include configuration for new features or keep up with the Symfony best practices.
It is advised to examine the changes in the sulu/skeleton
repository between the versions you are upgrading and
apply them to your project if they make sense in your case.
This step cannot be automated, because changes in sulu/skeleton repository could include BC breaks or might simply not fit your project.
Note
For a convenient view of all changes in the skeleton repository, open https://github.com/sulu/skeleton/compare/
and the select your current version as base
and the target version as compare
.
3. Check the UPGRADE.md file for BC breaks¶
The UPGRADE.md file in the sulu/sulu
repository contains all changes breaking backwards compatibility
between different versions. These changes might break your application if you have used the changed part of Sulu
in a specific way.
In a majority of cases, the changes should not affect your project because backwards compatibility is only broken when it is really necessary to fix a bug. However, if something goes south, this file should contain an explanation what to change.
4. Update the Admin JavaScript build¶
Our administration interface requires a built version of its JavaScript code in the public/build/admin
folder of
the project. The JavaScript code might be adjusted between different versions to fix bugs or implement new features.
When upgrading the project, you need to update the build to match the new Sulu version.
To simplify this step, Sulu provides a command to update the JavaScript build in the project:
$ bin/console sulu:admin:update-build
Note
Have a look at the Building the administration interface frontend application documentation if you want to update the
JavaScript build in the project without using the sulu:admin:update-build
command.