Prepare a major version upgrade
Let's take an example and imagine your application is running on Symfony 4.2. You would like to migrate it to the latest Symfony version, Symfony 5.2.
As explained in the introduction to upgrade reports, upgrading between major versions (from 4 to 5) introduces backward incompatible changes. This means that in order to do this upgrade, you need to update the code of your application.
There are several steps to follow in order to do such an upgrade:
- Upgrade to the latest minor version
- Use deprecations to fix issues
- Migrate to the next major
Let's have a detailed look at each of these steps to better understand them.
1. Upgrade to the latest minor version
When following Semantic versioning, minor versions can be upgraded safely. In our case, this mean that we can safely upgrade from Symfony 6.2 to Symfony 6.4 without needing to change any of our code.
To do the upgrade, update your composer.json file to replace references to 6.2.*
by references to 6.4.* in symfony/* packages. Don't forget the extra.symfony.require
configuration key for Symfony Flex!
Then run composer update: you are now on Symfony 6.4!
It is interesting to note what happens when we do such an upgrade. In minor versions, when Symfony introduces new features to the framework, sometimes it also deprecates older features that were replaced.
These older features keep working until they are removed in the next major, but because Symfony deprecates them in the code, we can find where our application uses these older features.
This is why upgrading to the latest minor version available before the next major is essential: it ensures all deprecations will be available when analyzing the code.
2. Use deprecations to fix issues
Once upgraded to Symfony 6.4, our vendor directory now contains the code of Symfony 6.4, including the new deprecations that will help us find where we need to change our code.
There are several strategies to find deprecated usages in your code, and you should probably use the three of them as neither is able to find all deprecations alone:
- Using the Web Profiler toolbar: when running your application in development, the Web Profiler toolbar (on the bottom of your browser) displays an icon for deprecations. When you click on it, you will be able to see all deprecated usages in this specific request. Careful: this only includes the current requests, not all your app!
- Using the PHPUnit bridge: in most Symfony applications, when you launch your tests, you are using the Symfony PHPUnit Bridge. This bridge helps solve many problems, but it also allows you to see all the deprecated features you used in your tests. Have a look at the output of your tests to see if there are deprecated features there! Careful: this only includes the code that is run by PHPUnit, not all your app! If your tests are not covering enough, you may miss deprecations.
- Using the SymfonyInsight Upgrade reports: because both the Web Profiler toolbar and the PHPUnit bridge cannot find all deprecations, we created at SymfonyInsight what we call Upgrade reports. These reports summarize all the deprecated usages we found in your application, in your whole app! This tool is therefore very useful to help you fix deprecations in your code.
Upgrade reports are computed on each analysis of your code: in an analysis report, you can click on the "Upgrade" tab to see the analysis results and fix them.
Here is an example of how an Upgrade report looks like:
3. Migrate to the next major
Once you have fixed all deprecations detected in your project, you can now upgrade to the next major version (in our case Symfony 7.0).
To do the upgrade, update your composer.json file to replace references to 6.4.*
by references to 7.0.* in symfony/* packages. Don't forget the extra.symfony.require
configuration key for Symfony Flex!
Then run composer update: you are now on Symfony 7.0!
Note: if the Composer command fails, it may be because a package you rely on needs to be upgraded as well in order to support Symfony 7. Have a look at their documentation!