]> git.immae.eu Git - github/wallabag/wallabag.git/blame - vendor/twig/twig/doc/api.rst
gitignore vendor
[github/wallabag/wallabag.git] / vendor / twig / twig / doc / api.rst
CommitLineData
4f5b44bd
NL
1Twig for Developers
2===================
3
4This chapter describes the API to Twig and not the template language. It will
5be most useful as reference to those implementing the template interface to
6the application and not those who are creating Twig templates.
7
8Basics
9------
10
11Twig uses a central object called the **environment** (of class
12``Twig_Environment``). Instances of this class are used to store the
13configuration and extensions, and are used to load templates from the file
14system or other locations.
15
16Most applications will create one ``Twig_Environment`` object on application
17initialization and use that to load templates. In some cases it's however
18useful to have multiple environments side by side, if different configurations
19are in use.
20
21The simplest way to configure Twig to load templates for your application
22looks roughly like this::
23
24 require_once '/path/to/lib/Twig/Autoloader.php';
25 Twig_Autoloader::register();
26
27 $loader = new Twig_Loader_Filesystem('/path/to/templates');
28 $twig = new Twig_Environment($loader, array(
29 'cache' => '/path/to/compilation_cache',
30 ));
31
32This will create a template environment with the default settings and a loader
33that looks up the templates in the ``/path/to/templates/`` folder. Different
34loaders are available and you can also write your own if you want to load
35templates from a database or other resources.
36
37.. note::
38
39 Notice that the second argument of the environment is an array of options.
40 The ``cache`` option is a compilation cache directory, where Twig caches
41 the compiled templates to avoid the parsing phase for sub-sequent
42 requests. It is very different from the cache you might want to add for
43 the evaluated templates. For such a need, you can use any available PHP
44 cache library.
45
46To load a template from this environment you just have to call the
47``loadTemplate()`` method which then returns a ``Twig_Template`` instance::
48
49 $template = $twig->loadTemplate('index.html');
50
51To render the template with some variables, call the ``render()`` method::
52
53 echo $template->render(array('the' => 'variables', 'go' => 'here'));
54
55.. note::
56
57 The ``display()`` method is a shortcut to output the template directly.
58
59You can also load and render the template in one fell swoop::
60
61 echo $twig->render('index.html', array('the' => 'variables', 'go' => 'here'));
62
63.. _environment_options:
64
65Environment Options
66-------------------
67
68When creating a new ``Twig_Environment`` instance, you can pass an array of
69options as the constructor second argument::
70
71 $twig = new Twig_Environment($loader, array('debug' => true));
72
73The following options are available:
74
75* ``debug``: When set to ``true``, the generated templates have a
76 ``__toString()`` method that you can use to display the generated nodes
77 (default to ``false``).
78
79* ``charset``: The charset used by the templates (default to ``utf-8``).
80
81* ``base_template_class``: The base template class to use for generated
82 templates (default to ``Twig_Template``).
83
84* ``cache``: An absolute path where to store the compiled templates, or
85 ``false`` to disable caching (which is the default).
86
87* ``auto_reload``: When developing with Twig, it's useful to recompile the
88 template whenever the source code changes. If you don't provide a value for
89 the ``auto_reload`` option, it will be determined automatically based on the
90 ``debug`` value.
91
92* ``strict_variables``: If set to ``false``, Twig will silently ignore invalid
93 variables (variables and or attributes/methods that do not exist) and
94 replace them with a ``null`` value. When set to ``true``, Twig throws an
95 exception instead (default to ``false``).
96
97* ``autoescape``: If set to ``true``, auto-escaping will be enabled by default
98 for all templates (default to ``true``). As of Twig 1.8, you can set the
99 escaping strategy to use (``html``, ``js``, ``false`` to disable).
100 As of Twig 1.9, you can set the escaping strategy to use (``css``, ``url``,
101 ``html_attr``, or a PHP callback that takes the template "filename" and must
102 return the escaping strategy to use -- the callback cannot be a function name
103 to avoid collision with built-in escaping strategies).
104
105* ``optimizations``: A flag that indicates which optimizations to apply
106 (default to ``-1`` -- all optimizations are enabled; set it to ``0`` to
107 disable).
108
109Loaders
110-------
111
112Loaders are responsible for loading templates from a resource such as the file
113system.
114
115Compilation Cache
116~~~~~~~~~~~~~~~~~
117
118All template loaders can cache the compiled templates on the filesystem for
119future reuse. It speeds up Twig a lot as templates are only compiled once; and
120the performance boost is even larger if you use a PHP accelerator such as APC.
121See the ``cache`` and ``auto_reload`` options of ``Twig_Environment`` above
122for more information.
123
124Built-in Loaders
125~~~~~~~~~~~~~~~~
126
127Here is a list of the built-in loaders Twig provides:
128
129``Twig_Loader_Filesystem``
130..........................
131
132.. versionadded:: 1.10
133 The ``prependPath()`` and support for namespaces were added in Twig 1.10.
134
135``Twig_Loader_Filesystem`` loads templates from the file system. This loader
136can find templates in folders on the file system and is the preferred way to
137load them::
138
139 $loader = new Twig_Loader_Filesystem($templateDir);
140
141It can also look for templates in an array of directories::
142
143 $loader = new Twig_Loader_Filesystem(array($templateDir1, $templateDir2));
144
145With such a configuration, Twig will first look for templates in
146``$templateDir1`` and if they do not exist, it will fallback to look for them
147in the ``$templateDir2``.
148
149You can add or prepend paths via the ``addPath()`` and ``prependPath()``
150methods::
151
152 $loader->addPath($templateDir3);
153 $loader->prependPath($templateDir4);
154
155The filesystem loader also supports namespaced templates. This allows to group
156your templates under different namespaces which have their own template paths.
157
158When using the ``setPaths()``, ``addPath()``, and ``prependPath()`` methods,
159specify the namespace as the second argument (when not specified, these
160methods act on the "main" namespace)::
161
162 $loader->addPath($templateDir, 'admin');
163
164Namespaced templates can be accessed via the special
165``@namespace_name/template_path`` notation::
166
167 $twig->render('@admin/index.html', array());
168
169``Twig_Loader_String``
170......................
171
172``Twig_Loader_String`` loads templates from strings. It's a dummy loader as
173the template reference is the template source code::
174
175 $loader = new Twig_Loader_String();
176 $twig = new Twig_Environment($loader);
177
178 echo $twig->render('Hello {{ name }}!', array('name' => 'Fabien'));
179
180This loader should only be used for unit testing as it has severe limitations:
181several tags, like ``extends`` or ``include`` do not make sense to use as the
182reference to the template is the template source code itself.
183
184``Twig_Loader_Array``
185.....................
186
187``Twig_Loader_Array`` loads a template from a PHP array. It's passed an array
188of strings bound to template names::
189
190 $loader = new Twig_Loader_Array(array(
191 'index.html' => 'Hello {{ name }}!',
192 ));
193 $twig = new Twig_Environment($loader);
194
195 echo $twig->render('index.html', array('name' => 'Fabien'));
196
197This loader is very useful for unit testing. It can also be used for small
198projects where storing all templates in a single PHP file might make sense.
199
200.. tip::
201
202 When using the ``Array`` or ``String`` loaders with a cache mechanism, you
203 should know that a new cache key is generated each time a template content
204 "changes" (the cache key being the source code of the template). If you
205 don't want to see your cache grows out of control, you need to take care
206 of clearing the old cache file by yourself.
207
208``Twig_Loader_Chain``
209.....................
210
211``Twig_Loader_Chain`` delegates the loading of templates to other loaders::
212
213 $loader1 = new Twig_Loader_Array(array(
214 'base.html' => '{% block content %}{% endblock %}',
215 ));
216 $loader2 = new Twig_Loader_Array(array(
217 'index.html' => '{% extends "base.twig" %}{% block content %}Hello {{ name }}{% endblock %}',
218 'base.html' => 'Will never be loaded',
219 ));
220
221 $loader = new Twig_Loader_Chain(array($loader1, $loader2));
222
223 $twig = new Twig_Environment($loader);
224
225When looking for a template, Twig will try each loader in turn and it will
226return as soon as the template is found. When rendering the ``index.html``
227template from the above example, Twig will load it with ``$loader2`` but the
228``base.html`` template will be loaded from ``$loader1``.
229
230``Twig_Loader_Chain`` accepts any loader that implements
231``Twig_LoaderInterface``.
232
233.. note::
234
235 You can also add loaders via the ``addLoader()`` method.
236
237Create your own Loader
238~~~~~~~~~~~~~~~~~~~~~~
239
240All loaders implement the ``Twig_LoaderInterface``::
241
242 interface Twig_LoaderInterface
243 {
244 /**
245 * Gets the source code of a template, given its name.
246 *
247 * @param string $name string The name of the template to load
248 *
249 * @return string The template source code
250 */
251 function getSource($name);
252
253 /**
254 * Gets the cache key to use for the cache for a given template name.
255 *
256 * @param string $name string The name of the template to load
257 *
258 * @return string The cache key
259 */
260 function getCacheKey($name);
261
262 /**
263 * Returns true if the template is still fresh.
264 *
265 * @param string $name The template name
266 * @param timestamp $time The last modification time of the cached template
267 */
268 function isFresh($name, $time);
269 }
270
271As an example, here is how the built-in ``Twig_Loader_String`` reads::
272
273 class Twig_Loader_String implements Twig_LoaderInterface
274 {
275 public function getSource($name)
276 {
277 return $name;
278 }
279
280 public function getCacheKey($name)
281 {
282 return $name;
283 }
284
285 public function isFresh($name, $time)
286 {
287 return false;
288 }
289 }
290
291The ``isFresh()`` method must return ``true`` if the current cached template
292is still fresh, given the last modification time, or ``false`` otherwise.
293
294.. tip::
295
296 As of Twig 1.11.0, you can also implement ``Twig_ExistsLoaderInterface``
297 to make your loader faster when used with the chain loader.
298
299Using Extensions
300----------------
301
302Twig extensions are packages that add new features to Twig. Using an
303extension is as simple as using the ``addExtension()`` method::
304
305 $twig->addExtension(new Twig_Extension_Sandbox());
306
307Twig comes bundled with the following extensions:
308
309* *Twig_Extension_Core*: Defines all the core features of Twig.
310
311* *Twig_Extension_Escaper*: Adds automatic output-escaping and the possibility
312 to escape/unescape blocks of code.
313
314* *Twig_Extension_Sandbox*: Adds a sandbox mode to the default Twig
315 environment, making it safe to evaluate untrusted code.
316
317* *Twig_Extension_Optimizer*: Optimizes the node tree before compilation.
318
319The core, escaper, and optimizer extensions do not need to be added to the
320Twig environment, as they are registered by default.
321
322Built-in Extensions
323-------------------
324
325This section describes the features added by the built-in extensions.
326
327.. tip::
328
329 Read the chapter about extending Twig to learn how to create your own
330 extensions.
331
332Core Extension
333~~~~~~~~~~~~~~
334
335The ``core`` extension defines all the core features of Twig:
336
337* :doc:`Tags <tags/index>`;
338* :doc:`Filters <filters/index>`;
339* :doc:`Functions <functions/index>`;
340* :doc:`Tests <tests/index>`.
341
342Escaper Extension
343~~~~~~~~~~~~~~~~~
344
345The ``escaper`` extension adds automatic output escaping to Twig. It defines a
346tag, ``autoescape``, and a filter, ``raw``.
347
348When creating the escaper extension, you can switch on or off the global
349output escaping strategy::
350
351 $escaper = new Twig_Extension_Escaper('html');
352 $twig->addExtension($escaper);
353
354If set to ``html``, all variables in templates are escaped (using the ``html``
355escaping strategy), except those using the ``raw`` filter:
356
357.. code-block:: jinja
358
359 {{ article.to_html|raw }}
360
361You can also change the escaping mode locally by using the ``autoescape`` tag
362(see the :doc:`autoescape<tags/autoescape>` doc for the syntax used before
363Twig 1.8):
364
365.. code-block:: jinja
366
367 {% autoescape 'html' %}
368 {{ var }}
369 {{ var|raw }} {# var won't be escaped #}
370 {{ var|escape }} {# var won't be double-escaped #}
371 {% endautoescape %}
372
373.. warning::
374
375 The ``autoescape`` tag has no effect on included files.
376
377The escaping rules are implemented as follows:
378
379* Literals (integers, booleans, arrays, ...) used in the template directly as
380 variables or filter arguments are never automatically escaped:
381
382 .. code-block:: jinja
383
384 {{ "Twig<br />" }} {# won't be escaped #}
385
386 {% set text = "Twig<br />" %}
387 {{ text }} {# will be escaped #}
388
389* Expressions which the result is always a literal or a variable marked safe
390 are never automatically escaped:
391
392 .. code-block:: jinja
393
394 {{ foo ? "Twig<br />" : "<br />Twig" }} {# won't be escaped #}
395
396 {% set text = "Twig<br />" %}
397 {{ foo ? text : "<br />Twig" }} {# will be escaped #}
398
399 {% set text = "Twig<br />" %}
400 {{ foo ? text|raw : "<br />Twig" }} {# won't be escaped #}
401
402 {% set text = "Twig<br />" %}
403 {{ foo ? text|escape : "<br />Twig" }} {# the result of the expression won't be escaped #}
404
405* Escaping is applied before printing, after any other filter is applied:
406
407 .. code-block:: jinja
408
409 {{ var|upper }} {# is equivalent to {{ var|upper|escape }} #}
410
411* The `raw` filter should only be used at the end of the filter chain:
412
413 .. code-block:: jinja
414
415 {{ var|raw|upper }} {# will be escaped #}
416
417 {{ var|upper|raw }} {# won't be escaped #}
418
419* Automatic escaping is not applied if the last filter in the chain is marked
420 safe for the current context (e.g. ``html`` or ``js``). ``escaper`` and
421 ``escaper('html')`` are marked safe for html, ``escaper('js')`` is marked
422 safe for javascript, ``raw`` is marked safe for everything.
423
424 .. code-block:: jinja
425
426 {% autoescape 'js' %}
427 {{ var|escape('html') }} {# will be escaped for html and javascript #}
428 {{ var }} {# will be escaped for javascript #}
429 {{ var|escape('js') }} {# won't be double-escaped #}
430 {% endautoescape %}
431
432.. note::
433
434 Note that autoescaping has some limitations as escaping is applied on
435 expressions after evaluation. For instance, when working with
436 concatenation, ``{{ foo|raw ~ bar }}`` won't give the expected result as
437 escaping is applied on the result of the concatenation, not on the
438 individual variables (so, the ``raw`` filter won't have any effect here).
439
440Sandbox Extension
441~~~~~~~~~~~~~~~~~
442
443The ``sandbox`` extension can be used to evaluate untrusted code. Access to
444unsafe attributes and methods is prohibited. The sandbox security is managed
445by a policy instance. By default, Twig comes with one policy class:
446``Twig_Sandbox_SecurityPolicy``. This class allows you to white-list some
447tags, filters, properties, and methods::
448
449 $tags = array('if');
450 $filters = array('upper');
451 $methods = array(
452 'Article' => array('getTitle', 'getBody'),
453 );
454 $properties = array(
455 'Article' => array('title', 'body'),
456 );
457 $functions = array('range');
458 $policy = new Twig_Sandbox_SecurityPolicy($tags, $filters, $methods, $properties, $functions);
459
460With the previous configuration, the security policy will only allow usage of
461the ``if`` tag, and the ``upper`` filter. Moreover, the templates will only be
462able to call the ``getTitle()`` and ``getBody()`` methods on ``Article``
463objects, and the ``title`` and ``body`` public properties. Everything else
464won't be allowed and will generate a ``Twig_Sandbox_SecurityError`` exception.
465
466The policy object is the first argument of the sandbox constructor::
467
468 $sandbox = new Twig_Extension_Sandbox($policy);
469 $twig->addExtension($sandbox);
470
471By default, the sandbox mode is disabled and should be enabled when including
472untrusted template code by using the ``sandbox`` tag:
473
474.. code-block:: jinja
475
476 {% sandbox %}
477 {% include 'user.html' %}
478 {% endsandbox %}
479
480You can sandbox all templates by passing ``true`` as the second argument of
481the extension constructor::
482
483 $sandbox = new Twig_Extension_Sandbox($policy, true);
484
485Optimizer Extension
486~~~~~~~~~~~~~~~~~~~
487
488The ``optimizer`` extension optimizes the node tree before compilation::
489
490 $twig->addExtension(new Twig_Extension_Optimizer());
491
492By default, all optimizations are turned on. You can select the ones you want
493to enable by passing them to the constructor::
494
495 $optimizer = new Twig_Extension_Optimizer(Twig_NodeVisitor_Optimizer::OPTIMIZE_FOR);
496
497 $twig->addExtension($optimizer);
498
499Twig supports the following optimizations:
500
501* ``Twig_NodeVisitor_Optimizer::OPTIMIZE_ALL``, enables all optimizations
502 (this is the default value).
503* ``Twig_NodeVisitor_Optimizer::OPTIMIZE_NONE``, disables all optimizations.
504 This reduces the compilation time, but it can increase the execution time
505 and the consumed memory.
506* ``Twig_NodeVisitor_Optimizer::OPTIMIZE_FOR``, optimizes the ``for`` tag by
507 removing the ``loop`` variable creation whenever possible.
508* ``Twig_NodeVisitor_Optimizer::OPTIMIZE_RAW_FILTER``, removes the ``raw``
509 filter whenever possible.
510* ``Twig_NodeVisitor_Optimizer::OPTIMIZE_VAR_ACCESS``, simplifies the creation
511 and access of variables in the compiled templates whenever possible.
512
513Exceptions
514----------
515
516Twig can throw exceptions:
517
518* ``Twig_Error``: The base exception for all errors.
519
520* ``Twig_Error_Syntax``: Thrown to tell the user that there is a problem with
521 the template syntax.
522
523* ``Twig_Error_Runtime``: Thrown when an error occurs at runtime (when a filter
524 does not exist for instance).
525
526* ``Twig_Error_Loader``: Thrown when an error occurs during template loading.
527
528* ``Twig_Sandbox_SecurityError``: Thrown when an unallowed tag, filter, or
529 method is called in a sandboxed template.