Introduction to Upgrade reports
Note
The Upgrade reports feature is only available on Team plans. You can manage your current plan on your account page.
Semantic versioning
Symfony, as many other frameworks and PHP tools, relies on Composer to
manage its dependencies. When you create a Symfony project, a composer.json
file is automatically created in order to let you describe what dependencies your
application relies on.
In this composer.json file, the two most important elements are the list of
dependencies (packages) you want to install and their associated versions.
As libraries and framework developers started to use such versions, they realized that they needed a way to express what users of their library should expect from their version numbers. This is where semantic versioning come from.
Semantic versioning is a version naming convention defining software versions
using 3 numbers separated by dots: MAJOR.MINOR.PATCH (for instance, Symfony 6.4.7).
For a version number MAJOR.MINOR.PATCH, libraries developers increment the:
- MAJOR version when they make incompatible API changes,
- MINOR version when they add functionality in a backwards compatible manner, and
- PATCH version when they make backwards compatible bug fixes.
The concept of Backward Compatibility is key here: by following Semantic versioning, a library ensures its users that when they upgrade from a MINOR to another, their application is going to work the same without any code change needed.
On the other hand, MAJOR versions do introduce incompatible changes, thus requiring application code changes.
The limitations of Semantic versioning
This technique is immensely useful in order to build applications which are stable over time. This is why nowadays, most of PHP packages, like Symfony, Doctrine or Twig, follow this versioning strategy.
Semantic versioning does have drawbacks though. By avoiding breaking changes between minors, it groups these changes in single major releases. This makes upgrading between major versions harder, as more things change at once.
This is where SymfonyInsight Upgrade reports are useful.
Using Upgrade reports to migrate major versions
SymfonyInsight Upgrade reports help you update your code during minor upgrades, by notifying you where you use deprecated features that are going to disappear in the next major version. By using Upgrade reports, upgrading major versions is much easier and take less time.
Every time your code is analyzed on our server, we automatically analyze if for upgrades as well.
Here is an example of how an Upgrade report looks like:
As you can see, SymfonyInsight analyzes your code to find usages of deprecated features, groups these usages by package and displays them to you with the reason why the feature is deprecated.
In this image's example, upgrading from SonataAdminBundle 3 to 4 requires to update the
application code in 3 places, one being related to the method getTemplate() being deprecated.