Symfony Upgrade Guide: 2.7 to 3.1

Versions 3.0* and 3.1* of Symfony are out for developers and the community is all abuzz with the neat features introduced for developers in these versions. I have already covered the features introduced in Symfony 3.1 and if you are not setup Symfony playground then follow the Symfony installation and get ready for it.

There are still developers who are working on the older 2.x version of the framework. In order to take the full advantage of the features of the 3.x versions of Symfony platform, it is important that developers update to the latest version.

In this article, I will discuss how to upgrade from Symfony 2.7 to Symfony 2.8, and then to Symfony 3.x. An upgrade to version 2.8 is called a minor update while upgrading to version 3.x is called a major update. Version 3.x comes with a whole new directory structure that also changes the location of several key files and components.

First Upgrade To Symfony 2.8

Apps created in Symfony 2.7 need to be upgraded to version 2.8 before they will upgrade to 3.x versions because version 2.7 have now some deprecated features which are not present in latest versions. Since this is a minor update, the code should remain intact with minimal issues.

To upgrade, open composer.json and replace the Symfony version 2.7 with 2.8.

Now open SSH terminal and run the following command :

$ composer update symfony/symfony --with-dependencies

This command will install the latest stable version of Symfony 2.8 in the application and will update all the dependencies present in composer.json

If you don’t want to restrict the app to the beta version, just replace 2.7 with 2.8.* and run the update command. The app should work fine without any broken code. There might be some issues with forms because several form methods and properties are deprecated in version 2.8.*

Deprecated Methods Of Forms In Symfony 2.8

Forms contain some properties that are deprecated in Symfony 2.8.

1. Cascade_validation attribute is deprecated. Use the constraint option with valid() method.

$form = $this->createFormBuilder($article, array('cascade_validation' => true))
       ->add('author', new AuthorType())
       ->getForm();

Change this to:

use Symfony\Component\Validator\Constraints\Valid;

   $form = $this->createFormBuilder($article)
       ->add('author', new AuthorType(), array(
           'constraints' => new Valid(),
       ))
       ->getForm();

2. Type names are also deprecated. You will now not referencing class name but their fully qualified class-name.

$form = $this->createFormBuilder()
       ->add('name', 'text')
       ->add('age', 'integer')
       ->getForm();

Change this to,

use Symfony\Component\Form\Extension\Core\Type\IntegerType;
   use Symfony\Component\Form\Extension\Core\Type\TextType;

   $form = $this->createFormBuilder()
       ->add('name', TextType::class)
       ->add('age', IntegerType::class)
       ->getForm();

3. Returning type instances from `FormTypeInterface::getParent()` is deprecated. Return the fully-qualified class name of the parent type class instead.

  class MyType
   {
       public function getParent()
       {
           return new ParentType();      
 }

 }

Change this to:

   class MyType
   {
       public function getParent()
       {
           return ParentType::class;
       }
   }

4.Passing type instances to `Form::add()`, `FormBuilder::add()` and the
`FormFactory::create*()` methods is deprecated and will not be supported anymore in Symfony 3.0. Pass the fully-qualified class name of the type instead.

 $form = $this->createForm(new MyType());

Change this to

   $form = $this->createForm(MyType::class);

The whole list of deprecated methods is available at this upgrade log.

Moving To The New Directory Structure Of Symfony 3.0

As mentioned in the introduction, Symfony 3.0 has a great new directory structure. You no longer have to worry about the logs and cache files and all the code will now reside in the App folder.

The New Directory “var”

Symfony 3 has introduced a new directory called var, which now holds the logs and cache files. First, you need to create the directory and then you could move the files in it.

Overriding Methods in Appkernel.php

Along with creating a new directory, some methods must be overridden in app/AppKernel.php to update the application. Copy and paste the following in Appkernel.php:

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

These methods will update the var directory and integrate it with the Symfony core.

Move Console to Bin

The next step is to move the console file from app folder to bin. You must remember to update the autoloader after this.

This will move the console file to bin. Now open it in the editor and replace the following line.

require_once __DIR__.'/bootstrap.php.cache';

with

require __DIR__.'/../app/autoload.php';

Updating Paths in Composer.json File

Now, update the paths for the newly created directories in composer.json. Open it and move to extra attribute and add the following lines in it.

 "extra": {
        "symfony-app-dir": "app",
        "symfony-web-dir": "web",
        "symfony-var-dir": "var",
        "symfony-bin-dir": "bin",
        "symfony-assets-install": "relative",
        "incenteev-parameters": {
            "file": "app/config/parameters.yml"
        },

Finally Upgrade To Symfony 3

Now you are all setup to update to Symfony 3. Open composer.json and move to Symfony version declaration and replace it. Find this line:

 "symfony/symfony": "2.8.*",

And replace it with:

 "symfony/symfony": "~3.1",

Now run the update command in composer.

$ composer update symfony/symfony --with-dependencies

After the installation, run the console command and check the version of Symfony.

$ php bin/console

You will see the upgraded version of Symfony.

Final Words

Upgrading Symfony 2.x to 3.x version is pretty much easy. If done right, there is little chance that the move will break the code. You can also check the documentation of Knpuniversity. I recommend that you upgrade to the latest versions because Symfony 3.1 is a highly optimized framework and has a great new directory structure.

If you have a query or face any issues while doing the upgrade, leave a comment for us!