Symfony 2.3 LTS (Long Term Support) was finally released yesterday (Monday June 3rd 2013). This is a new Symfony2 version that will be supported for next three years. This is significantly longer than the 8 months that normal releases are maintained for. Longer support means less upgrades and can reduce maintenance costs (although the upgrades will be bigger). Also the promise not to break backward compatibility from this version on is an important one. The complete release process (and the release diagram below) can be found on the Symfony2 release process page of the Symfony website.

Our LeaseWeb Symfony bundles have all received minor version upgrades to support this new Symfony 2.3 release. However, please report any issues you might find with these new versions.

In previous major version upgrades there was an “UPGRADE.md” (for upgrading from 2.0 to 2.1) and “UPGRADE-2.2.md” (for upgrading from 2.1 to 2.2). This release does not have the file included (probably a mistake), but fortunately you can find “UPGRADE-2.3.md” on the official Github repository and also some upgrade instructions on the official blog. Read it carefully to avoid hitting the issues we found (they are described below).

1: Running LTS with stable versions

To run only stable versions of packagist packages make sure “composer.json” contains the following line:

"minimum-stability": "stable",

It would be strange to run an LTS version with development code wouldn’t it? This is set correctly on a fresh Symfony 2.3 installation, but you should check it locally on your own file to be sure it is set correctly.

2: JMS bundles are missing

When you replace the requirements from your composer.json with the required section from the Symfony 2.3 “composer.json” file, you might get the following error when running the “php composer.phar update”:

PHP Fatal error:  Class 'JMS\AopBundle\JMSAopBundle' not found in app/AppKernel.php on line 19

This happens because there are two lines removed from the composer.json compared to the previous versions:

"jms/security-extra-bundle": "1.2.*",
"jms/di-extra-bundle": "1.1.*",

You should add them again, but with different versions:

"jms/security-extra-bundle": "1.5.*",
"jms/di-extra-bundle": "1.3.*@dev",

Note that in the future, you might want to remove the “@dev” suffix from “jms/di-extra-bundle” that allows the package to run a non-stable version.

Update June 8th 2013: There is a new stable version “jms/di-extra-bundle”, but unfortunately this does not work yet:

"jms/security-extra-bundle": "1.5.*",
"jms/di-extra-bundle": "1.4.*",

This caused by the dependencies on “jms/security-extra-bundle” that have not been adjusted to reflect this new stable version. It complains:

jms/security-extra-bundle 1.5.0 requires jms/di-extra-bundle 1.3.* ...

Update June 9th 2013: There is a new stable version “jms/security-extra-bundle” and all dependencies have been fixed. Thank you!

3: “trust_proxy_headers” option unrecognized

You might run into the issue that the “trust_proxy_headers” option that was already deprecated is removed in Symfony 2.3:

[Symfony\Component\Config\Definition\Exception\InvalidConfigurationException]
Unrecognized options "trust_proxy_headers" under "framework"

To fix this issue open “app/config/config.yml” and remove the “trust_proxy_headers” option and replace it with an “trusted_proxies” option and specify the list of proxies as described in the FrameworkBundle Configuration documentation.

4: Method “hasFlash” does not exist

You might run into a issue with Flash Messages. Flash Messages are (unrelated to Adobe Flash) the green, blue, yellow or red bars that show up on a page that show the result of the previous page (form) submit. Normally they show messages like “Login successful”, “Error submitting form, please try again” or “Sign-up successful, an email has been sent”.

Method "hasFlash" for object "Symfony\Component\HttpFoundation\Session\Session"
does not exist in ::flash.html.twig at line 1

The “hasFlash” method is deprecated since version 2.1 and removed in 2.3. The book has a good section on how to handle flash messages in different versions. To summarize, if you have this:

{% if app.session.hasFlash('success') %}
  {{ app.session.flash('success') }}
{% endif %}

You need to change that construct into this:

{% for flashMessage in app.session.flashbag.get('success') %}
  {{ flashMessage }}
{% endfor %}

Make sure you also change all “setFlash” calls with the following search/replace action: ”setFlash” -> “getFlashBag()->add”.

5: Method ”bindRequest” does not exist

Make sure you also change all your “bindRequest” calls to “bind” like this:

$form->bind($request); // was: $form->bindRequest($request);

As was well described in the Form Goodness in Symfony 2.1 post.

6: Change Forms (Types) and Validators

In the Type classes add the following use clause:

use Symfony\Component\OptionsResolver\OptionsResolverInterface;

Step 1: Replace the “getDefaultOptions” function like this:

public function getDefaultOptions(array $options)

with:

public function setDefaultOptions(OptionsResolverInterface $resolver)

Step 2: Replace the return value with a call to the resolver “setDefaults” method like this:

return array('validation_constraint' => $collectionConstraint);

with:

$resolver->setDefaults(array('constraints' => $collectionConstraint));

Step 3: Also in your custom validators replace the function “isValid” like this:

public function isValid($value, Constraint $constraint)

with:

public function validate($value, Constraint $constraint)

7: The method “getEntityManager” is deprecated

Replace the deprecated “getEntityManager” method by “getManager” in your controllers like this:

$em = $this->getDoctrine()->getEntityManager();

with:

$em = $this->getDoctrine()->getManager();

As you can also read in the “Persisting Objects to the Database” chapter of the book.

8: The “Min” and “Max” validators are removed

The Min and Max constraints that are deprecated since version 2.1 are removed in Symfony 2.3. You should use Range validator with the “min” and/or “max” option instead.

9: Yours…

If you run into other issues please post them and I’ll add them to this list. For now enjoy this brand new stable Symfony 2.3!