Upgrading a Minor Version (e.g. 4.0.0 to 4.1.0)
Edit this pageWarning: You are browsing the documentation for Symfony 5.1, which is no longer maintained.
Read the updated version of this page for Symfony 6.3 (the current stable version).
Upgrading a Minor Version (e.g. 4.0.0 to 4.1.0)
If you're upgrading a minor version (where the middle number changes), then you should not encounter significant backward compatibility changes. For details, see the Symfony backward compatibility promise.
However, some backwards-compatibility breaks are possible and you'll learn in a second how to prepare for them.
There are two steps to upgrading a minor version:
1) Update the Symfony Library via Composer
The composer.json file is configured to allow Symfony packages to be
upgraded to patch versions. But to upgrade to a new minor version, you will
probably need to update the version constraint next to each library starting
symfony/. Suppose you are upgrading from Symfony 4.3 to 4.4:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
{
"...": "...",
"require": {
- "symfony/cache": "4.3.*",
+ "symfony/cache": "4.4.*",
- "symfony/config": "4.3.*",
+ "symfony/config": "4.4.*",
- "symfony/console": "4.3.*",
+ "symfony/console": "4.4.*",
"...": "...",
"...": "A few libraries starting with
symfony/ follow their versioning scheme. You
do not need to update these versions: you can
upgrade them independently whenever you want",
"symfony/monolog-bundle": "^3.5",
},
"...": "...",
}Your composer.json file should also have an extra block that you will
also need to update:
1 2 3 4 5 6 7
"extra": {
"symfony": {
"...": "...",
- "require": "4.3.*"
+ "require": "4.4.*"
}
}Next, use Composer to download new versions of the libraries:
1
$ composer update "symfony/*"Dependency Errors
If you get a dependency error, it may mean that you also need to upgrade
other libraries that are dependencies of the Symfony libraries. To allow
that, pass the --with-all-dependencies flag:
1
$ composer update "symfony/*" --with-all-dependenciesThis updates symfony/* and all packages that those packages depend on.
By using tight version constraints in composer.json, you can control what
versions each library upgrades to.
If this still doesn't work, your composer.json file may specify a version
for a library that is not compatible with the newer Symfony version. In that
case, updating that library to a newer version in composer.json may solve
the issue.
Or, you may have deeper issues where different libraries depend on conflicting versions of other libraries. Check your error message to debug.
Another issue that may happen is that the project dependencies can be installed on your local computer but not on the remote server. This usually happens when the PHP versions are different on each machine. The solution is to add the platform config option to your `composer.json` file to define the highest PHP version allowed for the dependencies (set it to the server's PHP version).
Upgrading other Packages
You may also want to upgrade the rest of your libraries. If you've done a
good job with your version constraints in composer.json, you can do
this safely by running:
1
$ composer updateCaution
Beware, if you have some unspecific version constraints in your
composer.json (e.g. dev-master), this could upgrade some
non-Symfony libraries to new versions that contain backwards-compatibility
breaking changes.
2) Updating your Code to Work with the new Version
In theory, you should be done! However, you may need to make a few changes to your code to get everything working. Additionally, some features you're using might still work, but might now be deprecated. While that's fine, if you know about these deprecations, you can start to fix them over time.
Every version of Symfony comes with an UPGRADE file (e.g. UPGRADE-4.4.md) included in the Symfony directory that describes these changes. If you follow the instructions in the document and update your code accordingly, it should be safe to update in the future.
These documents can also be found in the Symfony Repository.
3) Updating Recipes
Over time - and especially when you upgrade to a new version of a library - an updated version of the recipe may be available. These updates are usually minor - e.g. new comments in a configuration file - but it's a good idea to keep your files in sync with the recipes.
Symfony Flex provides several commands to help upgrade your recipes. Be sure to commit any unrelated changes you're working on before starting:
1.6
The recipes commands were introduced in Symfony Flex 1.6.
1 2 3 4 5 6 7 8
# see a list of all installed recipes and which have updates available
$ composer recipes
# see detailed information about a specific recipes
$ composer recipes symfony/framework-bundle
# update a specific recipes
$ composer recipes:install symfony/framework-bundle --force -vThe tricky part of this process is that the recipe "update" does not perform any intelligent "upgrading" of your code. Instead, the updates process re-installs the latest version of the recipe which means that your custom code will be overridden completely. After updating a recipe, you need to carefully choose which changes you want, and undo the rest.
Screencast
For a detailed example, see the SymfonyCasts Symfony 5 Upgrade Tutorial.
