1Deprecated Features
2===================
3
4This document lists deprecated features in Twig 2.x. Deprecated features are
5kept for backward compatibility and removed in the next major release (a
6feature that was deprecated in Twig 2.x is removed in Twig 3.0).
7
8PSR-0
9-----
10
11* PSR-0 classes are deprecated in favor of namespaced ones since Twig 2.7.
12
13Inheritance
14-----------
15
16* Defining a "block" definition in a non-capturing block in a child template is
17  deprecated since Twig 2.5.0. In Twig 3.0, it will throw a
18  ``Twig\Error\SyntaxError`` exception. It does not work anyway, so most
19  projects won't need to do anything to upgrade.
20
21Errors
22------
23
24* Passing a string as the ``$source`` argument on ``\Twig\Error\Error`` /
25  ``Twig\Error\Error`` constructor is deprecated since Twig 2.6.1. Pass an
26  instance of ``Twig\Source`` instead.
27
28Tags
29----
30
31* The ``spaceless`` tag is deprecated in Twig 2.7. Use the ``spaceless`` filter
32  instead or ``{% apply spaceless %}`` (the ``Twig\Node\SpacelessNode`` and
33  ``Twig\TokenParser\SpacelessTokenParser`` classes are also deprecated).
34
35* Using the ``spaceless`` tag at the root level of a child template is
36  deprecated in Twig 2.5.0. This does not work as one would expect it to work
37  anyway. In Twig 3.0, it will throw a ``Twig\Error\SyntaxError`` exception.
38
39* The ``filter`` tag is deprecated in Twig 2.9. Use the ``apply`` tag instead
40  (the ``Twig\TokenParser\FilterTokenParser`` classes is also deprecated).
41
42* Adding an ``if`` condition on a ``for`` tag is deprecated in Twig 2.10. Use a
43  ``filter`` filter or an "if" condition inside the "for" body instead (if your condition
44  depends on a variable updated inside the loop).
45
46Final Classes
47-------------
48
49The following classes are marked as ``@final`` in Twig 2 and will be final in
503.0:
51
52* ``Twig\Node\ModuleNode``
53* ``Twig\TwigFilter``
54* ``Twig\TwigFunction``
55* ``Twig\TwigTest``
56* ``Twig\Profiler\Profile``
57
58Parser
59------
60
61* As of Twig 2.7, the ``\Twig\Parser::isReservedMacroName()`` / ``Twig\Parser``
62  function is deprecated and will be removed in Twig 3.0. It always returns
63  ``false`` anyway as Twig 2 does not have any reserved macro names.
64
65Environment
66-----------
67
68* As of Twig 2.7, the ``base_template_class`` option on ``Twig\Environment`` is
69  deprecated and will be removed in Twig 3.0.
70
71* As of Twig 2.7, the ``Twig\Environment::getBaseTemplateClass()`` and
72  ``Twig\Environment::setBaseTemplateClass()`` methods are deprecated and will
73  be removed in Twig 3.0.
74
75* As of Twig 2.7, the ``Twig\Environment::getTemplateClass()`` is marked as
76  being internal and should not be used.
77
78* As of Twig 2.7, passing a ``Twig\Template`` instance to the
79  ``Twig\Environment::load()`` and ``Twig\Environment::resolveTemplate()`` is
80  deprecated.
81
82* Depending on the input, ``Twig\Environment::resolveTemplate()`` can return
83  a ``Twig\Template`` or a ``Twig\TemplateWrapper`` instance. In Twig 3.0, this
84  method will **always** return a ``Twig\TemplateWrapper`` instance. You should
85  only rely on the methods of this class if you want to be forward-compatible.
86
87Interfaces
88----------
89
90* As of Twig 2.7, the empty ``Twig\Loader\ExistsLoaderInterface`` interface is
91  deprecated and will be removed in Twig 3.0.
92
93* As of Twig 2.7, the ``Twig\Extension\InitRuntimeInterface`` interface is
94  deprecated and will be removed in Twig 3.0.
95
96Extensions
97----------
98
99* As of Twig 2.11, the ``Twig\Extension\CoreExtension::setEscaper()`` and
100  ``Twig\Extension\CoreExtension::getEscapers()`` are deprecated. Use the same
101  methods on ``Twig\Extension\EscaperExtension`` instead.
102
103Miscellaneous
104-------------
105
106* As of Twig 2.7, the ``Twig_SimpleFilter``, ``Twig_SimpleFunction``, and
107  ``Twig_SimpleTest`` empty classes are deprecated and will be removed in Twig
108  3.0. Use ``Twig\TwigFilter``, ``Twig\TwigFunction``, and ``Twig\TwigTest``
109  respectively.
110
111* As of Twig 2.8.2, all usage of
112  ``Twig\Loader\FilesystemLoader::findTemplate()`` check for a ``null`` return
113  value (same meaning as returning ``false``). If you are overidding
114  ``Twig\Loader\FilesystemLoader::findTemplate()``, you must return ``null`` instead of ``false``
115  to be compatible with Twig 3.0.
116