December 03, 2015 Albéric Trancart 5 min read

A new major version is always exciting: when it comes to one of our favorite frameworks like Symfony, it’s Christmas come early for developers. But is is also worrisome. Will my application break? Will I have to rewrite half of my code? Don’t panic! We will go through the 3.0 major version changes and cover various subjects from new features to upgrading.

What’s up doc?

To be honest, there is no new shiny feature in this version. What? You said Symfony 3.0 was awesome! Yeah, Symfony 3.0 is awesome exactly because of that.

Let’s go back to one rule of semantic versioning:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced.

As a consequence, Symfony 3.0 is allowed to break compatibility. It does little else. And this is necessary: at some point, you need to clean the compatibility layers burdening your framework. But to avoid most of the pain, the Symfony developers used a well designed release schedule:

Major features were introduced in 2.7 and 2.8 (which was released at the same time as 3.0)

2.7 and 2.8 are backward compatible

Since 2.6 users are notified about deprecated methods when they are used

All compatibility layers are dropped in the 3.0 version

If you are interested in shiny features and have not moved to 2.7 yet, you might want to read this:

The framework has become more standard (support of the PSR-3 standard for logging), has got rid of some architecture mistakes and is more decoupled and reusable than ever. Here are the notable changes:

A new directory structure

Basically, the entire structure of Symfony didn’t change but there were some tweaks:

2.5 directory structure | 3.0 directory structure app/cache | var/cache app/logs | var/log app/bootstrap.php.cache | var/bootstrap.php.cache app/console | bin/console app/phpunit.xml.dist | phpunit.xml.dist

As a result, you can run PHPUnit without specifying a config file: phpunit instead of phunit -c app . All binaries are moved into the bin directory and the new var directory was made for easier permission settings (the entire directory should be writable).

New components

The Asset component was introduced in 2.7 and automatically manages URL generation and versioning of your stylesheets, javascript files and images.

The LDAP component was introduced in 2.8 and allows you to use an LDAP service as a security provider.

A PHPUnit bridge was added in 2.7. Its main advantage is that use of depreciated code is reported and tests will fail because of that. With this bridge it will be easier for you to stay up to date.

Profiler improvements

The Twig and Translation profilers were added. Furthermore, the whole debug interface was redesigned to have a nicer look and a better user experience.

How to upgrade to 3.0

First of all, PHP 5.5 is the new required version to run Symfony 3.0. Check that your servers are running 5.5 or newer PHP versions, if not consider upgrading PHP.

Now, you need to check the migration status of installed bundles. Here is a Google Doc summing up migration statuses of major bundles.

As for the code itself, this is the easiest part. And you should do it even if you don’t meet the above requirements because 2.7 and 2.8 came with great performance and security improvements. Updating to a new LTS (Long Term Support) version when it comes out (2.8) is also a good practice for maintainability.

A method that should work in most cases:

Update to 2.8.X. There is no compatibility breaks in minor versions, so your website will still be running.

Quickly install the Deprecation Detector utility.

Run deprecation-detector check in your Symfony app. It will list all deprecated methods and classes with a hint on how to fix the issue.

in your Symfony app. It will list all deprecated methods and classes with a hint on how to fix the issue. If you need more details you can check the full UPGRADE guide.

What’s next?

Be careful though, the 3.0 version is not an LTS one. The last LTS version is 2.8 and the next one is the 3.3 to be released in May 2017.

Concerning PHP7 (this is a great month for PHP lovers), Symfony will not move to this version yet, but a bump to PHP 5.6 next year is being considered.

As 3.0 is not that a revolution (but a needed cleaning process), development will continue normally in the next months to come.

Conclusion

Even if you don’t upgrade now (but you really should), you can move to 2.8 which is an LTS and have warnings about deprecated methods that are removed from the 3.0 version. Migration from Symfony 1 to Symfony 2 was (and still is) a terrifying journey. With the Backwards Compatibility Promise, the Symfony development team wanted to build a more lasting framework and produced a nice and smooth migration process for 3.0.

The official blog post