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