aleph1.co.uk Git - yaffs-website/blob - vendor/twig/twig/doc/deprecated.rst

   1 Deprecated Features
   2 ===================
   3
   4 This document lists all deprecated features in Twig. Deprecated features are
   5 kept for backward compatibility and removed in the next major release (a
   6 feature that was deprecated in Twig 1.x is removed in Twig 2.0).
   7
   8 Deprecation Notices
   9 -------------------
  10
  11 As of Twig 1.21, Twig generates deprecation notices when a template uses
  12 deprecated features. See :ref:`deprecation-notices` for more information.
  13
  14 Macros
  15 ------
  16
  17 As of Twig 2.0, macros imported in a file are not available in child templates
  18 anymore (via an ``include`` call for instance). You need to import macros
  19 explicitly in each file where you are using them.
  20
  21 Token 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
  35 Extensions
  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_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_ExtensionInterface::getGlobals()`` method is
  49   deprecated. Implement ``Twig_Extension_GlobalsInterface`` to avoid
  50   deprecation notices.
  51
  52 * As of Twig 1.26, the ``Twig_ExtensionInterface::getName()`` method is
  53   deprecated and it is not used internally anymore.
  54
  55 PEAR
  56 ----
  57
  58 PEAR support has been discontinued in Twig 1.15.1, and no PEAR packages are
  59 provided anymore. Use Composer instead.
  60
  61 Filters
  62 -------
  63
  64 * As of Twig 1.x, use ``Twig_SimpleFilter`` 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_SimpleFilter`` class is deprecated and will be
  75   removed in Twig 3.x (use ``Twig_Filter`` instead). In Twig 2.x,
  76   ``Twig_SimpleFilter`` is just an alias for ``Twig_Filter``.
  77
  78 Functions
  79 ---------
  80
  81 * As of Twig 1.x, use ``Twig_SimpleFunction`` 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_SimpleFunction`` class is deprecated and will be
  92   removed in Twig 3.x (use ``Twig_Function`` instead). In Twig 2.x,
  93   ``Twig_SimpleFunction`` is just an alias for ``Twig_Function``.
  94
  95 Tests
  96 -----
  97
  98 * As of Twig 1.x, use ``Twig_SimpleTest`` 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_SimpleTest`` class is deprecated and will be
 109   removed in Twig 3.x (use ``Twig_Test`` instead). In Twig 2.x,
 110   ``Twig_SimpleTest`` 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
 115 Tags
 116 ----
 117
 118 * As of Twig 1.x, the ``raw`` tag is deprecated. You should use ``verbatim``
 119   instead.
 120
 121 Nodes
 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``
 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_Module`` is
 132   deprecated. Use ``getName()`` instead.
 133
 134 * As of Twig 1.27, the ``Twig_Node::getFilename()/Twig_Node::getLine()``
 135   methods are deprecated, use
 136   ``Twig_Node::getTemplateName()/Twig_Node::getTemplateLine()`` instead.
 137
 138 Interfaces
 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`` instead)
 147 * ``Twig_ParserInterface``       (use ``Twig_Parser`` instead)
 148 * ``Twig_ExistsLoaderInterface`` (merged with ``Twig_LoaderInterface``)
 149 * ``Twig_SourceContextLoaderInterface`` (merged with ``Twig_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
 154 Compiler
 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
 163 Loaders
 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_LoaderInterface::getSource()`` is deprecated.
 170   Implement ``Twig_SourceContextLoaderInterface`` instead and use
 171   ``getSourceContext()``.
 172
 173 Node Visitors
 174 -------------
 175
 176 * Because of the removal of ``Twig_NodeInterface`` in 2.0, you need to extend
 177   ``Twig_BaseNodeVisitor`` instead of implementing ``Twig_NodeVisitorInterface``
 178   directly to make your node visitors compatible with both Twig 1.x and 2.x.
 179
 180 Globals
 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
 194 Miscellaneous
 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::getTemplateFile()`` and
 213   ``Twig_Error::setTemplateFile()`` are deprecated. Use
 214   ``Twig_Error::getTemplateName()`` and ``Twig_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.