doc/deprecated.rst
8563e040
 Deprecated Features
 ===================
 
0372d72c
 This document lists all deprecated features in Twig. Deprecated features are
 kept for backward compatibility and removed in the next major release (a
 feature that was deprecated in Twig 1.x is removed in Twig 2.0).
8563e040
 
bd87ba8a
 Deprecation Notices
 -------------------
 
 As of Twig 1.21, Twig generates deprecation notices when a template uses
 deprecated features. See :ref:`deprecation-notices` for more information.
 
c9a14464
 Macros
 ------
 
 As of Twig 2.0, macros imported in a file are not available in child templates
 anymore (via an ``include`` call for instance). You need to import macros
 explicitly in each file where you are using them.
 
8563e040
 Token Parsers
 -------------
 
0372d72c
 * As of Twig 1.x, the token parser broker sub-system is deprecated. The
   following class and interface will be removed in 2.0:
8563e040
 
   * ``Twig_TokenParserBrokerInterface``
   * ``Twig_TokenParserBroker``
0a7b37b8
 
3632a46e
 * As of Twig 1.27, ``\Twig\Parser::getFilename()`` is deprecated. From a token
6c76583e
   parser, use ``$this->parser->getStream()->getSourceContext()->getPath()`` instead.
d77f3dd3
 
3632a46e
 * As of Twig 1.27, ``\Twig\Parser::getEnvironment()`` is deprecated.
4deb03ae
 
0a7b37b8
 Extensions
 ----------
 
0372d72c
 * As of Twig 1.x, the ability to remove an extension is deprecated and the
3632a46e
   ``\Twig\Environment::removeExtension()`` method will be removed in 2.0.
c5f5b891
 
3632a46e
 * As of Twig 1.23, the ``\Twig\Extension\ExtensionInterface::initRuntime()`` method is
9774f4f1
   deprecated. You have two options to avoid the deprecation notice: if you
   implement this method to store the environment for your custom filters,
   functions, or tests, use the ``needs_environment`` option instead; if you
   have more complex needs, explicitly implement
3632a46e
   ``\Twig\Extension\InitRuntimeInterface`` (not recommended).
9774f4f1
 
3632a46e
 * As of Twig 1.23, the ``\Twig\Extension\ExtensionInterface::getGlobals()`` method is
   deprecated. Implement ``\Twig\Extension\GlobalsInterface`` to avoid
e3a325f2
   deprecation notices.
 
3632a46e
 * As of Twig 1.26, the ``\Twig\Extension\ExtensionInterface::getName()`` method is
71f03df0
   deprecated and it is not used internally anymore.
 
c5f5b891
 PEAR
 ----
 
06ca7f98
 PEAR support has been discontinued in Twig 1.15.1, and no PEAR packages are
f4c41f78
 provided anymore. Use Composer instead.
0372d72c
 
1918edef
 Filters
 -------
 
3632a46e
 * As of Twig 1.x, use ``\Twig\TwigFilter`` to add a filter. The following
1918edef
   classes and interfaces will be removed in 2.0:
 
   * ``Twig_FilterInterface``
   * ``Twig_FilterCallableInterface``
   * ``Twig_Filter``
   * ``Twig_Filter_Function``
   * ``Twig_Filter_Method``
   * ``Twig_Filter_Node``
 
3632a46e
 * As of Twig 2.x, the ``\Twig\TwigFilter`` class is deprecated and will be
1918edef
   removed in Twig 3.x (use ``Twig_Filter`` instead). In Twig 2.x,
3632a46e
   ``\Twig\TwigFilter`` is just an alias for ``Twig_Filter``.
1918edef
 
 Functions
 ---------
 
3632a46e
 * As of Twig 1.x, use ``\Twig\TwigFunction`` to add a function. The following
1918edef
   classes and interfaces will be removed in 2.0:
 
   * ``Twig_FunctionInterface``
   * ``Twig_FunctionCallableInterface``
   * ``Twig_Function``
   * ``Twig_Function_Function``
   * ``Twig_Function_Method``
   * ``Twig_Function_Node``
 
3632a46e
 * As of Twig 2.x, the ``\Twig\TwigFunction`` class is deprecated and will be
1918edef
   removed in Twig 3.x (use ``Twig_Function`` instead). In Twig 2.x,
3632a46e
   ``\Twig\TwigFunction`` is just an alias for ``Twig_Function``.
1918edef
 
 Tests
 -----
 
3632a46e
 * As of Twig 1.x, use ``\Twig\TwigTest`` to add a test. The following classes
1918edef
   and interfaces will be removed in 2.0:
 
   * ``Twig_TestInterface``
   * ``Twig_TestCallableInterface``
   * ``Twig_Test``
   * ``Twig_Test_Function``
   * ``Twig_Test_Method``
   * ``Twig_Test_Node``
 
3632a46e
 * As of Twig 2.x, the ``\Twig\TwigTest`` class is deprecated and will be
1918edef
   removed in Twig 3.x (use ``Twig_Test`` instead). In Twig 2.x,
3632a46e
   ``\Twig\TwigTest`` is just an alias for ``Twig_Test``.
1918edef
 
52c952c1
 * The ``sameas`` and ``divisibleby`` tests are deprecated in favor of ``same
   as`` and ``divisible by`` respectively.
 
c27b04c9
 Tags
 ----
 
 * As of Twig 1.x, the ``raw`` tag is deprecated. You should use ``verbatim``
   instead.
 
0b2f373f
 Nodes
 -----
 
 * As of Twig 1.x, ``Node::toXml()`` is deprecated and will be removed in Twig
   2.0.
 
3632a46e
 * As of Twig 1.26, ``Node::$nodes`` should only contains ``\Twig\Node\Node``
48a6df29
   instances, storing a ``null`` value is deprecated and won't be possible in
   Twig 2.x.
 
3632a46e
 * As of Twig 1.27, the ``filename`` attribute on ``\Twig\Node\ModuleNode`` is
d03297ed
   deprecated. Use ``getName()`` instead.
 
3632a46e
 * As of Twig 1.27, the ``\Twig\Node\Node::getFilename()/\Twig\Node\Node::getLine()``
39d94dfb
   methods are deprecated, use
3632a46e
   ``\Twig\Node\Node::getTemplateName()/\Twig\Node\Node::getTemplateLine()`` instead.
6c76583e
 
0372d72c
 Interfaces
 ----------
 
 * As of Twig 2.x, the following interfaces are deprecated and empty (they will
   be removed in Twig 3.0):
 
3632a46e
 * ``Twig_CompilerInterface``     (use ``\Twig\Compiler`` instead)
 * ``Twig_LexerInterface``        (use ``\Twig\Lexer`` instead)
 * ``Twig_NodeInterface``         (use ``\Twig\Node\Node`` instead)
 * ``Twig_ParserInterface``       (use ``\Twig\Parser`` instead)
 * ``\Twig\Loader\ExistsLoaderInterface`` (merged with ``\Twig\Loader\LoaderInterface``)
 * ``\Twig\Loader\SourceContextLoaderInterface`` (merged with ``\Twig\Loader\LoaderInterface``)
 * ``Twig_TemplateInterface``     (use ``\Twig\Template`` instead, and use
   those constants \Twig\Template::ANY_CALL, \Twig\Template::ARRAY_CALL,
   \Twig\Template::METHOD_CALL)
5abad160
 
48a6df29
 Compiler
 --------
 
3632a46e
 * As of Twig 1.26, the ``\Twig\Compiler::getFilename()`` has been deprecated.
48a6df29
   You should not use it anyway as its values is not reliable.
 
3632a46e
 * As of Twig 1.27, the ``\Twig\Compiler::addIndentation()`` has been deprecated.
   Use ``\Twig\Compiler::write('')`` instead.
bc499a47
 
3779435d
 Loaders
 -------
 
 * As of Twig 1.x, ``Twig_Loader_String`` is deprecated and will be removed in
3632a46e
   2.0. You can render a string via ``\Twig\Environment::createTemplate()``.
3779435d
 
3632a46e
 * As of Twig 1.27, ``\Twig\Loader\LoaderInterface::getSource()`` is deprecated.
   Implement ``\Twig\Loader\SourceContextLoaderInterface`` instead and use
21ecba8c
   ``getSourceContext()``.
 
881fb63b
 Node Visitors
 -------------
 
 * Because of the removal of ``Twig_NodeInterface`` in 2.0, you need to extend
3632a46e
   ``\Twig\NodeVisitor\AbstractNodeVisitor`` instead of implementing ``\Twig\NodeVisitor\NodeVisitorInterface``
881fb63b
   directly to make your node visitors compatible with both Twig 1.x and 2.x.
 
5abad160
 Globals
 -------
 
 * As of Twig 2.x, the ability to register a global variable after the runtime
   or the extensions have been initialized is not possible anymore (but
   changing the value of an already registered global is possible).
61eb80b0
 
b490e659
 * As of Twig 1.x, using the ``_self`` global variable to get access to the
3632a46e
   current ``\Twig\Template`` instance is deprecated; most usages only need the
b490e659
   current template name, which will continue to work in Twig 2.0. In Twig 2.0,
   ``_self`` returns the current template name instead of the current
3632a46e
   ``\Twig\Template`` instance. If you are using ``{{ _self.templateName }}``,
8ab764b4
   just replace it with ``{{ _self }}``.
5514c8ee
 
61eb80b0
 Miscellaneous
 -------------
 
3632a46e
 * As of Twig 1.x, ``\Twig\Environment::clearTemplateCache()``,
   ``\Twig\Environment::writeCacheFile()``,
   ``\Twig\Environment::clearCacheFiles()``,
   ``\Twig\Environment::getCacheFilename()``,
   ``\Twig\Environment::getTemplateClassPrefix()``,
   ``\Twig\Environment::getLexer()``, ``\Twig\Environment::getParser()``, and
   ``\Twig\Environment::getCompiler()`` are deprecated and will be removed in 2.0.
cacfb069
 
3632a46e
 * As of Twig 1.x, ``\Twig\Template::getEnvironment()`` and
c9501b80
   ``Twig_TemplateInterface::getEnvironment()`` are deprecated and will be
   removed in 2.0.
b399ec0d
 
70d03042
 * As of Twig 1.21, setting the environment option ``autoescape`` to ``true`` is
73de309f
   deprecated and will be removed in 2.0. Use ``"html"`` instead.
70d03042
 
3632a46e
 * As of Twig 1.27, ``\Twig\Error\Error::getTemplateFile()`` and
   ``\Twig\Error\Error::setTemplateFile()`` are deprecated. Use
   ``\Twig\Error\Error::getTemplateName()`` and ``\Twig\Error\Error::setTemplateName()``
b399ec0d
   instead.
7598f27e
 
3632a46e
 * As of Twig 1.27, ``\Twig\Template::getSource()`` is deprecated. Use
   ``\Twig\Template::getSourceContext()`` instead.
31c444b5
 
3632a46e
 * As of Twig 1.27, ``\Twig\Parser::addHandler()`` and
   ``\Twig\Parser::addNodeVisitor()`` are deprecated and will be removed in 2.0.
e89c712f
 
 * As of Twig 1.29, some classes are marked as being final via the `@final`
   annotation. Those classes will be marked as final in 2.0.