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
 
d77f3dd3
 * As of Twig 1.27, ``Twig_Parser::getFilename()`` is deprecated. From a token
6c76583e
   parser, use ``$this->parser->getStream()->getSourceContext()->getPath()`` instead.
d77f3dd3
 
4deb03ae
 * As of Twig 1.27, ``Twig_Parser::getEnvironment()`` is deprecated.
 
0a7b37b8
 Extensions
 ----------
 
0372d72c
 * As of Twig 1.x, the ability to remove an extension is deprecated and the
0a7b37b8
   ``Twig_Environment::removeExtension()`` method will be removed in 2.0.
c5f5b891
 
9774f4f1
 * As of Twig 1.23, the ``Twig_ExtensionInterface::initRuntime()`` method is
   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
   ``Twig_Extension_InitRuntimeInterface`` (not recommended).
 
e3a325f2
 * As of Twig 1.23, the ``Twig_ExtensionInterface::getGlobals()`` method is
   deprecated. Implement ``Twig_Extension_GlobalsInterface`` to avoid
   deprecation notices.
 
71f03df0
 * As of Twig 1.26, the ``Twig_ExtensionInterface::getName()`` method is
   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
 -------
 
 * As of Twig 1.x, use ``Twig_SimpleFilter`` to add a filter. The following
   classes and interfaces will be removed in 2.0:
 
   * ``Twig_FilterInterface``
   * ``Twig_FilterCallableInterface``
   * ``Twig_Filter``
   * ``Twig_Filter_Function``
   * ``Twig_Filter_Method``
   * ``Twig_Filter_Node``
 
 * As of Twig 2.x, the ``Twig_SimpleFilter`` class is deprecated and will be
   removed in Twig 3.x (use ``Twig_Filter`` instead). In Twig 2.x,
   ``Twig_SimpleFilter`` is just an alias for ``Twig_Filter``.
 
 Functions
 ---------
 
 * As of Twig 1.x, use ``Twig_SimpleFunction`` to add a function. The following
   classes and interfaces will be removed in 2.0:
 
   * ``Twig_FunctionInterface``
   * ``Twig_FunctionCallableInterface``
   * ``Twig_Function``
   * ``Twig_Function_Function``
   * ``Twig_Function_Method``
   * ``Twig_Function_Node``
 
 * As of Twig 2.x, the ``Twig_SimpleFunction`` class is deprecated and will be
   removed in Twig 3.x (use ``Twig_Function`` instead). In Twig 2.x,
   ``Twig_SimpleFunction`` is just an alias for ``Twig_Function``.
 
 Tests
 -----
 
 * As of Twig 1.x, use ``Twig_SimpleTest`` to add a test. The following classes
   and interfaces will be removed in 2.0:
 
   * ``Twig_TestInterface``
   * ``Twig_TestCallableInterface``
   * ``Twig_Test``
   * ``Twig_Test_Function``
   * ``Twig_Test_Method``
   * ``Twig_Test_Node``
 
 * As of Twig 2.x, the ``Twig_SimpleTest`` class is deprecated and will be
   removed in Twig 3.x (use ``Twig_Test`` instead). In Twig 2.x,
   ``Twig_SimpleTest`` is just an alias for ``Twig_Test``.
 
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.
 
48a6df29
 * As of Twig 1.26, ``Node::$nodes`` should only contains ``Twig_Node``
   instances, storing a ``null`` value is deprecated and won't be possible in
   Twig 2.x.
 
6c76583e
 * As of Twig 1.27, the ``filename`` attribute on ``Twig_Node_Module`` is
d03297ed
   deprecated. Use ``getName()`` instead.
 
39d94dfb
 * As of Twig 1.27, the ``Twig_Node::getFilename()/Twig_Node::getLine()``
   methods are deprecated, use
   ``Twig_Node::getTemplateName()/Twig_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):
 
83c7fc64
 * ``Twig_CompilerInterface``     (use ``Twig_Compiler`` instead)
 * ``Twig_LexerInterface``        (use ``Twig_Lexer`` instead)
 * ``Twig_NodeInterface``         (use ``Twig_Node`` instead)
 * ``Twig_ParserInterface``       (use ``Twig_Parser`` instead)
0372d72c
 * ``Twig_ExistsLoaderInterface`` (merged with ``Twig_LoaderInterface``)
21ecba8c
 * ``Twig_SourceContextLoaderInterface`` (merged with ``Twig_LoaderInterface``)
7b80c942
 * ``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
 --------
 
 * As of Twig 1.26, the ``Twig_Compiler::getFilename()`` has been deprecated.
   You should not use it anyway as its values is not reliable.
 
bc499a47
 * As of Twig 1.27, the ``Twig_Compiler::addIndentation()`` has been deprecated.
   Use ``Twig_Compiler::write('')`` instead.
 
3779435d
 Loaders
 -------
 
 * As of Twig 1.x, ``Twig_Loader_String`` is deprecated and will be removed in
b5c7f5cd
   2.0. You can render a string via ``Twig_Environment::createTemplate()``.
3779435d
 
21ecba8c
 * As of Twig 1.27, ``Twig_LoaderInterface::getSource()`` is deprecated.
   Implement ``Twig_SourceContextLoaderInterface`` instead and use
   ``getSourceContext()``.
 
881fb63b
 Node Visitors
 -------------
 
 * Because of the removal of ``Twig_NodeInterface`` in 2.0, you need to extend
0f5f9aaf
   ``Twig_BaseNodeVisitor`` instead of implementing ``Twig_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
   current ``Twig_Template`` instance is deprecated; most usages only need the
   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
8ab764b4
   ``Twig_Template`` instance. If you are using ``{{ _self.templateName }}``,
   just replace it with ``{{ _self }}``.
5514c8ee
 
61eb80b0
 Miscellaneous
 -------------
 
48a6df29
 * 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
 
c9501b80
 * As of Twig 1.x, ``Twig_Template::getEnvironment()`` and
   ``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
 
b399ec0d
 * As of Twig 1.27, ``Twig_Error::getTemplateFile()`` and
   ``Twig_Error::setTemplateFile()`` are deprecated. Use
   ``Twig_Error::getTemplateName()`` and ``Twig_Error::setTemplateName()``
   instead.
7598f27e
 
 * As of Twig 1.27, ``Twig_Template::getSource()`` is deprecated. Use
   ``Twig_Template::getSourceContext()`` instead.
31c444b5
 
 * 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.