Symfony News

Preparing your Applications for Twig 3

Twig, the template language used in Symfony and thousands of other projects, has three active development branches: 1.x is for legacy applications, 2.x is for current applications and 3.x will be the next stable version.

Unlike Symfony, older Twig branches still receive some new features. For example, 1.x received the new filter, map and reduce features and the new white space trimming options. However, sometimes new features need to deprecate some current behaviors. This cannot be done in 1.x and that's why features like the auto import of Twig macros are not available in 1.x.

Although Twig 1.x will be maintained for the foreseeable future, it will receive less and less new features, especially when Twig 3.x is released. The tentative release date of Twig 3 is before the end of 2019, so you should start upgrading your Twig 1.x usage now.

The main change needed to prepare for 3.x is to use the namespaced Twig classes (the non-namespaced classes are still available in 1.x and 2.x but deprecated, and they will be removed in 3.x):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

namespace App\Twig;

+use Twig\Extension\AbstractExtension;
+use Twig\TwigFilter;

-class AppExtension extends \Twig_Extension
+class AppExtension extends AbstractExtension
{
    public function getFilters()
    {
        return [
-            new \Twig_SimpleFilter('...', [$this, '...']),
+            new TwigFilter('...', [$this, '...']),
        ];
    }

    // ...
}

For most applications, these namespace updates are the only change you'll need to make to upgrade to Twig 3.x. However, if you make an advanced usage of Twig internals, you'll see other deprecated warnings. Check out the list of deprecated features in Twig 1.x and the list of deprecations in Twig 2.x.

Twig 3.x will be the most polished Twig release ever. It includes a ton of small tweaks, better error messages, better performance, better consistency and cleaner code. Get your applications ready for Twig 3 by upgrading them to 2.x as soon as possible.