Symfony2 LTS: how to upgrade from 2.3 to 2.7?

Question

Symfony 2.7 was released on 30th April 2015 and is the current LTS (Long Term Support) version after the 2.3 version. Maintenance for these versions will end on May 2016 for Symfony 2.3 and May 2018 for Symfony 2.7. Security fixes will be released during one year after end of maintenance for both versions.

As suggested by Massimiliano Arione in the announce comments, what are the changes required to upgrade from Symfony 2.3 from 2.7 without having to check all the minor upgrades (2.3 → 2.4, 2.4 → 2.5, etc.)?

Destructor

2.7 does not break compatibility with 2.3, it deprecates some class and methods. So putting 2.7 instead of 2.3 in your composer should be ok – Hockett

Med: you're right, but there is some few exceptions: github.com/symfony/symfony/issues/14377#issuecomment-94386014 github.com/symfony/symfony/blob/2.7/… – Destructor

If you are concerned with those exceptions, you have 2 choices, wait for a minor release to correct those, or modify your code. Maybe try an upgrade on a duplicate env and run some tests to be sure that your app is still fine – Hockett

@Med: these were some random examples to show that even if the developers try to avoid BC breaks, it's not always the case. – Destructor

Answer 1

As reminded by Med in a comment, Symfony2 developers have tried to keep backward compatibility in the 2.x branch. So as long as you don't want to switch to the 3.0 branch later, you can ignore the changes between 2.3 and 2.7 because they are mostly deprecation changes.

In order to upgrade you app from Symfony 2.3 to Symfony 2.7 you'll have to update your composer.json file:

([…] indicates unchanged code)

Old (2.3) version:

{
    […]
    "autoload": {
        "psr-0": { "": "src/" }
    },
    "require": {
        "php": ">=5.3.3",
        "symfony/symfony": "2.3.*",
        "doctrine/orm": "~2.2,>=2.2.3,<2.5",
        "doctrine/dbal": "<2.5",
        "doctrine/doctrine-bundle": "~1.2",
        "twig/extensions": "1.0.*",
        "symfony/assetic-bundle": "~2.3",
        "symfony/swiftmailer-bundle": "~2.3",
        "symfony/monolog-bundle": "~2.4",
        "sensio/distribution-bundle": "~2.3",
        "sensio/framework-extra-bundle": "~3.0,>=3.0.2",
        "sensio/generator-bundle": "~2.3",
        "incenteev/composer-parameter-handler": "~2.0"
    },
    "scripts": {
        "post-install-cmd": [
            "Incenteev\\ParameterHandler\\ScriptHandler::buildParameters",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::buildBootstrap",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::clearCache",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installAssets",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installRequirementsFile",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::prepareDeploymentTarget"
        ],
        "post-update-cmd": [
            "Incenteev\\ParameterHandler\\ScriptHandler::buildParameters",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::buildBootstrap",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::clearCache",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installAssets",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installRequirementsFile",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::prepareDeploymentTarget"
        ]
    },
    […]
    "minimum-stability": "stable",
    "extra": {
        […]
        "incenteev-parameters": {
            "file": "app/config/parameters.yml"
        },
        "branch-alias": {
            "dev-master": "2.3-dev"
        }
    }
}

New (2.7) version:

{
    […]
    "autoload": {
        "psr-4": { "": "src/", "SymfonyStandard\\": "app/SymfonyStandard/" }
    },
    "require": {
        "php": ">=5.3.9",
        "symfony/symfony": "2.7.*",
        "doctrine/orm": "^2.4.8",
        "doctrine/doctrine-bundle": "~1.4",
        "symfony/assetic-bundle": "~2.3",
        "symfony/swiftmailer-bundle": "~2.3",
        "symfony/monolog-bundle": "~2.4",
        "sensio/distribution-bundle": "~4.0",
        "sensio/framework-extra-bundle": "^3.0.2",
        "incenteev/composer-parameter-handler": "~2.0"
    },
    "require-dev": {
        "sensio/generator-bundle": "~2.3",
        "symfony/phpunit-bridge": "~2.7"
    },
    "scripts": {
        "post-install-cmd": [
            "Incenteev\\ParameterHandler\\ScriptHandler::buildParameters",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::buildBootstrap",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::clearCache",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installAssets",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installRequirementsFile",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::removeSymfonyStandardFiles",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::prepareDeploymentTarget"
        ],
        "post-update-cmd": [
            "Incenteev\\ParameterHandler\\ScriptHandler::buildParameters",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::buildBootstrap",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::clearCache",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installAssets",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::installRequirementsFile",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::removeSymfonyStandardFiles",
            "Sensio\\Bundle\\DistributionBundle\\Composer\\ScriptHandler::prepareDeploymentTarget"
        ]
    },
    […]
    "extra": {
        […]
        "symfony-assets-install": "relative",
        […]
        "branch-alias": {
            "dev-master": "2.7-dev"
        }
    }
}

Summary:

• Symfony version is updated
• PSR-4 is used instead of PSR-0
• twig/extensions is not installed by default, you may need to add it if you use Twig extensions
• sensio/generator-bundle is required only in dev environment
• scripts part has been updated
• "minimum-stability": "stable", has been removed

Once you have updated your composer.json file, you have to update the dependencies:

composer update --prefer-dist -vv

Then you may need to flush the cache:

php app/console cache:clear --env=dev

Note: I used the following command in order to get the composer.json files:

# create Symfony "2.3.*" project in the "2.3" directory
composer create-project symfony/framework-standard-edition "2.3" "2.3.*" --no-interaction -v
# create Symfony "2.7.*" project in the "2.7" directory
composer create-project symfony/framework-standard-edition "2.7" "2.7.*" --no-interaction -v
# compare the Symfony 2.3 and 2.7 composer.json files
diff -u 2.3/composer.json 2.7/composer.json

(we use 2.3.* and not 2.3 because we want the last version (2.3.31 today) and not the initial release (2.3.0))

The diff is available at GitHub too, but the composer.json file of Symfony 2.3 has been updated multiple times, so it may be different from your file.

Destructor

In the new version (2.7) you should change php requirement to "php": ">=5.3.9", because the "symfony/symfony": "2.7.*" package requires it. – Containerize

@DaniSancas you're right, but I don't understand why 5.3.3 is used in symfony-standard and 5.3.9 is used in symfony. – Destructor

Maybe they forgot to change it: I think I've seen that 5.3.3 requirement for Symfony 2.7 long ago before the first alpha release. Maybe they introduced something previously unexpected during the development that forced them to use 5.3.9 and then they forgot to change it somewhere else... But is just a theory, I don't really know why. – Containerize

Thanks @DaniSancas, I'll keep the file as the exact copy of the official one. I added an issue on GitHub. – Destructor

@DaniSancas the issue I posted on GitHub has been closed and the file has been updated, thank you for reporting this inconsistency between the 2 composer.json files. – Destructor

You're welcome @a-l, and thanks for the mention in the issue ^_^ – Containerize

How did you find composer changes ? I am not able to understand. @Destructor – Franco

@AnkiiGangrade see the last line of code. You have to change 2.3 to something other in order to get a specific version of Symfony with its dependencies. – Destructor

@Destructor : What is the meaning of both i.e, "2.3" and "2.3.*" in this command? Can you please let me know? – Franco

@AnkiiGangrade These are the name of the destination folder and the version required by composer. – Destructor

After you get your composer.json updated and composer update ran well, consider this migration guide [From Symfony 2.3 to Symfony 2.7] (gist.github.com/mickaelandrieu/5211d0047e7a6fbff925) – Groove