Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1)

Warning: You are browsing the documentation for Symfony 3.x, which is no longer maintained.

Read the updated version of this page for Symfony 7.2 (the current stable version).

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;
  2. Update your code to work with the new version.

1) Update the Symfony Library via Composer

First, you need to update Symfony by modifying your composer.json file to use the new version:

1
2
3
4
5
6
7
8
{
    "...": "...",

    "require": {
        "symfony/symfony": "2.6.*",
    },
    "...": "...",
}

Next, use Composer to download new versions of the libraries:

1
$ composer update symfony/symfony

Dependency Errors

If you get a dependency error, it may simply mean that you need to upgrade other Symfony dependencies too. In that case, try the following command:

1
$ composer update symfony/symfony --with-dependencies

This updates symfony/symfony and all packages that it depends on, which will include several other packages. 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 update

Caution

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 just 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-2.7.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.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version