Symfony LTS: how to upgrade from 2.8 to 3.4? - symfony

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?

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.

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