Symfony LTS: how to upgrade from 2.8 to 3.4?

Question

Symfony 2.8 is the last release of the 2.x branch and the previous LTS.

Symfony 3.4 is the last release of the 3.x branch and the current LTS.

What steps are required in order to upgrade Symfony from 2.8 to 3.4 and switch to this last LTS?

Rosaline

Answer 1

Prepare upgrade

Check that all the dependencies and bundles listed in composer.json have published a version compatible with Symfony 3.4, you can do this by searching each package on Packagist, for example EasyAdmin is compatible with Symfony 3 because the dependencies in the requires are not limited to Symfony 2 (we would see something like symfony/*: ~2.3). If one of the dependencies it not compatible with Symfony 3, you'll have to find replacement packages or patch these libraries.

composer.json

In order to upgrade you app from Symfony 2.8 to Symfony 3.4 you'll have to update your dependencies by changing your composer.json file:

([…] indicates unchanged code)

Old (2.8) version:

{
    […]
    "autoload-dev": {
        "files": [ "vendor/symfony/symfony/src/Symfony/Component/VarDumper/Resources/functions/dump.php" ]
     },
    "require": {
        "php": ">=5.3.9",
        "doctrine/doctrine-bundle": "~1.4",
        "doctrine/orm": "^2.4.8",
        "incenteev/composer-parameter-handler": "~2.0",
        "sensio/distribution-bundle": "~4.0",
        "sensio/framework-extra-bundle": "^3.0.2",
        "symfony/monolog-bundle": "^3.0.2",
        "symfony/swiftmailer-bundle": "~2.3,>=2.3.10",
        "symfony/symfony": "2.8.*",
        "twig/twig": "^1.0||^2.0"
    },
    "require-dev": {
        "sensio/generator-bundle": "~3.0",
        "symfony/phpunit-bridge": "~2.7"
    },
    "config": {
        "bin-dir": "bin",
        "platform": {
            "php": "5.6"
        },
        "sort-packages": true
    },
    "extra": {
        "symfony-app-dir": "app",
        "symfony-web-dir": "web",
        "symfony-assets-install": "relative",
        […]
        "branch-alias": {
            "dev-master": "2.8-dev"
        }
    }
}

New (3.4) version:

{
    […]
    "autoload-dev": {
        "psr-4": { "Tests\\": "tests/" },
        "files": [ "vendor/symfony/symfony/src/Symfony/Component/VarDumper/Resources/functions/dump.php" ]
     },
    "require": {
        "php": ">=5.5.9",
        "doctrine/doctrine-bundle": "^1.6",
        "doctrine/orm": "^2.5",
        "incenteev/composer-parameter-handler": "^2.0",
        "sensio/distribution-bundle": "^5.0.19",
        "sensio/framework-extra-bundle": "^5.0.0",
        "symfony/monolog-bundle": "^3.1.0",
        "symfony/polyfill-apcu": "^1.0",
        "symfony/swiftmailer-bundle": "^2.6.4",
        "symfony/symfony": "3.4.*",
        "twig/twig": "^1.0||^2.0"
    },
    "require-dev": {
        "sensio/generator-bundle": "^3.0",
        "symfony/phpunit-bridge": "^3.0"
    },
    "config": {
        "platform": {
            "php": "5.6"
        },
        "sort-packages": true
    },

    "extra": {
        "symfony-app-dir": "app",
        "symfony-bin-dir": "bin",
        "symfony-var-dir": "var",
        "symfony-web-dir": "web",
        "symfony-tests-dir": "tests",
        "symfony-assets-install": "relative",
        […]
        "branch-alias": {
            "dev-master": "3.4-dev"
        }
    }
}

Summary

• autoload-dev.psr-4 has been added (it has to be changed with the path to your tests directory)
• Symfony and dependencies are updated
• symfony/polyfill-apcu is a new dependency
• extra has been updated in order to use new directory structure: var for temporary files, etc.
• config.bin-dir has been removed

More details about upgrades: → 3.0, → 3.1, → 3.2, → 3.3, → 3.4

app/AppKernel.php

Add getRootDir and update registerContainerConfiguration functions:

public function getRootDir()
{
    return __DIR__;
}

public function registerContainerConfiguration(LoaderInterface $loader)
{
    $loader->load($this->getRootDir().'/config/config_'.$this->getEnvironment().'.yml');
}

Cache and logs

If you want to put cache and logs in var/, you have to update your app/AppKernel.php file by adding the following lines:

public function getCacheDir()
{
    return dirname(__DIR__).'/var/cache/'.$this->getEnvironment();
}
public function getLogDir()
{
    return dirname(__DIR__).'/var/logs';
}

Then create the var/ directory and put an empty file .gitkeep

And apply these changes to your .gitignore file:

/var/cache/*
/var/logs/*
!var/cache/.gitkeep
!var/logs/.gitkeep

See also: What is the new Symfony 3 directory structure?

Final steps

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

composer update

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.8.*" project in the "2.8" directory
composer create-project symfony/framework-standard-edition "2.8" "2.8.*" --no-interaction -v
# create Symfony "3.4.*" project in the "3.4" directory
composer create-project symfony/framework-standard-edition "3.4" "3.4.*" --no-interaction -v
# compare the Symfony 2.8 and 3.4 composer.json files
diff -u 2.8/composer.json 3.4/composer.json

The diff is available at GitHub too.

Bonus: enable autowiring of services.

Rosaline

So posting a question and then immediately answering it in this level of detail is a thing now? And you completely overlooked third party dependencies. That is often the real challenge. – Catcher

@Catcher my previous guide was well accepted and there's nothing wrong in answering your own question. I wrote this answer while updating one of my projects (with few dependencies) and it worked for me so I thought that it may help some other users. I agree that upgrading third party dependencies is the hardest part but I can't explain specific steps for every bundle. – Rosaline

@Catcher I added a note about dependencies, thanks for your input! – Rosaline

Answer 2

2019+ Instant Upgrades Version

Today, you can automate most of the work with instant upgrade tool called Rector (I'm author of). It has prepared sets for many frameworks, the Symfony ones are most complete. Also include PHP upgrade, that you might need.

You can read more about this particular upgrade path in: How to Upgrade Symfony 2.8 to 3.4

Duckpin

- Installation request for rector/rector ^0.6.14 -> satisfiable by rector/rector[v0.6.14]. - rector/rector v0.6.14 requires symfony/process ^4.4|^5.0 -> satisfiable by symfony/process[v4.4.0, v4.4.1, v4.4.2, v4.4.3, v5.0.0, v5.0.1, v5.0.2, v5.0.3]. - Installation request for symfony/symfony (locked at v2.8.52, required as 2.8.*) -> satisfiable by symfony/symfony[v2.8.52]. – Esprit

getrector.org/blog/2020/01/20/… – Duckpin