1Deprecated Features
2===================
3
4This document lists all deprecated features in Twig. Deprecated features are
5kept for backward compatibility and removed in the next major release (a
6feature that was deprecated in Twig 1.x is removed in Twig 2.0).
7
8Deprecation Notices
9-------------------
10
11As of Twig 1.21, Twig generates deprecation notices when a template uses
12deprecated features. See :ref:`deprecation-notices` for more information.
13
14Macros
15------
16
17As of Twig 2.0, macros imported in a file are not available in child templates
18anymore (via an ``include`` call for instance). You need to import macros
19explicitly in each file where you are using them.
20
21Token Parsers
22-------------
23
24* As of Twig 1.x, the token parser broker sub-system is deprecated. The
25  following class and interface will be removed in 2.0:
26
27  * ``Twig_TokenParserBrokerInterface``
28  * ``Twig_TokenParserBroker``
29
30* As of Twig 1.27, ``\Twig\Parser::getFilename()`` is deprecated. From a token
31  parser, use ``$this->parser->getStream()->getSourceContext()->getPath()`` instead.
32
33* As of Twig 1.27, ``\Twig\Parser::getEnvironment()`` is deprecated.
34
35Extensions
36----------
37
38* As of Twig 1.x, the ability to remove an extension is deprecated and the
39  ``\Twig\Environment::removeExtension()`` method will be removed in 2.0.
40
41* As of Twig 1.23, the ``\Twig\Extension\ExtensionInterface::initRuntime()`` method is
42  deprecated. You have two options to avoid the deprecation notice: if you
43  implement this method to store the environment for your custom filters,
44  functions, or tests, use the ``needs_environment`` option instead; if you
45  have more complex needs, explicitly implement
46  ``\Twig\Extension\InitRuntimeInterface`` (not recommended).
47
48* As of Twig 1.23, the ``\Twig\Extension\ExtensionInterface::getGlobals()`` method is
49  deprecated. Implement ``\Twig\Extension\GlobalsInterface`` to avoid
50  deprecation notices.
51
52* As of Twig 1.26, the ``\Twig\Extension\ExtensionInterface::getName()`` method is
53  deprecated and it is not used internally anymore.
54
55PEAR
56----
57
58PEAR support has been discontinued in Twig 1.15.1, and no PEAR packages are
59provided anymore. Use Composer instead.
60
61Filters
62-------
63
64* As of Twig 1.x, use ``\Twig\TwigFilter`` to add a filter. The following
65  classes and interfaces will be removed in 2.0:
66
67  * ``Twig_FilterInterface``
68  * ``Twig_FilterCallableInterface``
69  * ``Twig_Filter``
70  * ``Twig_Filter_Function``
71  * ``Twig_Filter_Method``
72  * ``Twig_Filter_Node``
73
74* As of Twig 2.x, the ``\Twig\TwigFilter`` class is deprecated and will be
75  removed in Twig 3.x (use ``Twig_Filter`` instead). In Twig 2.x,
76  ``\Twig\TwigFilter`` is just an alias for ``Twig_Filter``.
77
78Functions
79---------
80
81* As of Twig 1.x, use ``\Twig\TwigFunction`` to add a function. The following
82  classes and interfaces will be removed in 2.0:
83
84  * ``Twig_FunctionInterface``
85  * ``Twig_FunctionCallableInterface``
86  * ``Twig_Function``
87  * ``Twig_Function_Function``
88  * ``Twig_Function_Method``
89  * ``Twig_Function_Node``
90
91* As of Twig 2.x, the ``\Twig\TwigFunction`` class is deprecated and will be
92  removed in Twig 3.x (use ``Twig_Function`` instead). In Twig 2.x,
93  ``\Twig\TwigFunction`` is just an alias for ``Twig_Function``.
94
95Tests
96-----
97
98* As of Twig 1.x, use ``\Twig\TwigTest`` to add a test. The following classes
99  and interfaces will be removed in 2.0:
100
101  * ``Twig_TestInterface``
102  * ``Twig_TestCallableInterface``
103  * ``Twig_Test``
104  * ``Twig_Test_Function``
105  * ``Twig_Test_Method``
106  * ``Twig_Test_Node``
107
108* As of Twig 2.x, the ``\Twig\TwigTest`` class is deprecated and will be
109  removed in Twig 3.x (use ``Twig_Test`` instead). In Twig 2.x,
110  ``\Twig\TwigTest`` is just an alias for ``Twig_Test``.
111
112* The ``sameas`` and ``divisibleby`` tests are deprecated in favor of ``same
113  as`` and ``divisible by`` respectively.
114
115Tags
116----
117
118* As of Twig 1.x, the ``raw`` tag is deprecated. You should use ``verbatim``
119  instead.
120
121Nodes
122-----
123
124* As of Twig 1.x, ``Node::toXml()`` is deprecated and will be removed in Twig
125  2.0.
126
127* As of Twig 1.26, ``Node::$nodes`` should only contains ``\Twig\Node\Node``
128  instances, storing a ``null`` value is deprecated and won't be possible in
129  Twig 2.x.
130
131* As of Twig 1.27, the ``filename`` attribute on ``\Twig\Node\ModuleNode`` is
132  deprecated. Use ``getName()`` instead.
133
134* As of Twig 1.27, the ``\Twig\Node\Node::getFilename()/\Twig\Node\Node::getLine()``
135  methods are deprecated, use
136  ``\Twig\Node\Node::getTemplateName()/\Twig\Node\Node::getTemplateLine()`` instead.
137
138Interfaces
139----------
140
141* As of Twig 2.x, the following interfaces are deprecated and empty (they will
142  be removed in Twig 3.0):
143
144* ``Twig_CompilerInterface``     (use ``\Twig\Compiler`` instead)
145* ``Twig_LexerInterface``        (use ``\Twig\Lexer`` instead)
146* ``Twig_NodeInterface``         (use ``\Twig\Node\Node`` instead)
147* ``Twig_ParserInterface``       (use ``\Twig\Parser`` instead)
148* ``\Twig\Loader\ExistsLoaderInterface`` (merged with ``\Twig\Loader\LoaderInterface``)
149* ``\Twig\Loader\SourceContextLoaderInterface`` (merged with ``\Twig\Loader\LoaderInterface``)
150* ``Twig_TemplateInterface``     (use ``\Twig\Template`` instead, and use
151  those constants \Twig\Template::ANY_CALL, \Twig\Template::ARRAY_CALL,
152  \Twig\Template::METHOD_CALL)
153
154Compiler
155--------
156
157* As of Twig 1.26, the ``\Twig\Compiler::getFilename()`` has been deprecated.
158  You should not use it anyway as its values is not reliable.
159
160* As of Twig 1.27, the ``\Twig\Compiler::addIndentation()`` has been deprecated.
161  Use ``\Twig\Compiler::write('')`` instead.
162
163Loaders
164-------
165
166* As of Twig 1.x, ``Twig_Loader_String`` is deprecated and will be removed in
167  2.0. You can render a string via ``\Twig\Environment::createTemplate()``.
168
169* As of Twig 1.27, ``\Twig\Loader\LoaderInterface::getSource()`` is deprecated.
170  Implement ``\Twig\Loader\SourceContextLoaderInterface`` instead and use
171  ``getSourceContext()``.
172
173Node Visitors
174-------------
175
176* Because of the removal of ``Twig_NodeInterface`` in 2.0, you need to extend
177  ``\Twig\NodeVisitor\AbstractNodeVisitor`` instead of implementing ``\Twig\NodeVisitor\NodeVisitorInterface``
178  directly to make your node visitors compatible with both Twig 1.x and 2.x.
179
180Globals
181-------
182
183* As of Twig 2.x, the ability to register a global variable after the runtime
184  or the extensions have been initialized is not possible anymore (but
185  changing the value of an already registered global is possible).
186
187* As of Twig 1.x, using the ``_self`` global variable to get access to the
188  current ``\Twig\Template`` instance is deprecated; most usages only need the
189  current template name, which will continue to work in Twig 2.0. In Twig 2.0,
190  ``_self`` returns the current template name instead of the current
191  ``\Twig\Template`` instance. If you are using ``{{ _self.templateName }}``,
192  just replace it with ``{{ _self }}``.
193
194Miscellaneous
195-------------
196
197* As of Twig 1.x, ``\Twig\Environment::clearTemplateCache()``,
198  ``\Twig\Environment::writeCacheFile()``,
199  ``\Twig\Environment::clearCacheFiles()``,
200  ``\Twig\Environment::getCacheFilename()``,
201  ``\Twig\Environment::getTemplateClassPrefix()``,
202  ``\Twig\Environment::getLexer()``, ``\Twig\Environment::getParser()``, and
203  ``\Twig\Environment::getCompiler()`` are deprecated and will be removed in 2.0.
204
205* As of Twig 1.x, ``\Twig\Template::getEnvironment()`` and
206  ``Twig_TemplateInterface::getEnvironment()`` are deprecated and will be
207  removed in 2.0.
208
209* As of Twig 1.21, setting the environment option ``autoescape`` to ``true`` is
210  deprecated and will be removed in 2.0. Use ``"html"`` instead.
211
212* As of Twig 1.27, ``\Twig\Error\Error::getTemplateFile()`` and
213  ``\Twig\Error\Error::setTemplateFile()`` are deprecated. Use
214  ``\Twig\Error\Error::getTemplateName()`` and ``\Twig\Error\Error::setTemplateName()``
215  instead.
216
217* As of Twig 1.27, ``\Twig\Template::getSource()`` is deprecated. Use
218  ``\Twig\Template::getSourceContext()`` instead.
219
220* As of Twig 1.27, ``\Twig\Parser::addHandler()`` and
221  ``\Twig\Parser::addNodeVisitor()`` are deprecated and will be removed in 2.0.
222
223* As of Twig 1.29, some classes are marked as being final via the `@final`
224  annotation. Those classes will be marked as final in 2.0.
225