New in Twig: Deprecated tag

Contributed by
Yonel Ceruto
in #2696.

Deprecations are the key of our backward compatibility promise and allow a smooth upgrade process for Symfony apps. However, you can only trigger deprecations in PHP code, so you can't warn users when some Twig template or block are going to be deprecated.

That's why in Twig 1.36 and 2.6 we've added a new {% deprecated %} tag. First, it allows to deprecate entire templates, which is used in the following example to warn users that base.twig will be replaced by layout.twig:

1
2
3

{# base.twig #}
{% deprecated 'The "base.twig" template is deprecated, use "layout.twig" instead.' %}
{% extends 'layout.twig' %}

In addition to entire templates, you can also deprecate individual blocks:

1
2
3
4
5
6
7
8

{% block user_menu %}
    {% deprecated 'The "user_menu" block is deprecated, use "user_menu_actions" instead.' %}
    {{ block('user_menu_actions') }}
{% endblock %}

{% block user_menu_actions %}
    {# ... #}
{% endblock %}

Whenever Twig finds a {% deprecated %} tag, it generates a deprecation notice (via a call to PHP's trigger_error() function) so you can see those deprecations alongside the other normal Symfony deprecations.