Lines Matching refs:Twig
1 Twig for Developers
4 This chapter describes the API to Twig and not the template language. It will
6 the application and not those who are creating Twig templates.
11 Twig uses a central object called the **environment** (of class
12 ``\Twig\Environment``). Instances of this class are used to store the
16 Most applications will create one ``\Twig\Environment`` object on application
21 The simplest way to configure Twig to load templates for your application
24 require_once '/path/to/lib/Twig/Autoloader.php';
27 $loader = new \Twig\Loader\FilesystemLoader('/path/to/templates');
28 $twig = new \Twig\Environment($loader, [
40 The ``cache`` option is a compilation cache directory, where Twig caches
49 To load a template from a Twig environment, call the ``load()`` method which
50 returns a ``\Twig\TemplateWrapper`` instance::
56 Before Twig 1.28, you should use ``loadTemplate()`` instead which returns a
57 ``\Twig\Template`` instance.
72 The possibility to render blocks from the API was added in Twig 1.28.
84 When creating a new ``\Twig\Environment`` instance, you can pass an array of
87 $twig = new \Twig\Environment($loader, ['debug' => true]);
101 * ``base_template_class`` *string* (defaults to ``\Twig\Template``)
113 When developing with Twig, it's useful to recompile the
120 If set to ``false``, Twig will silently ignore invalid
122 replace them with a ``null`` value. When set to ``true``, Twig throws an
130 As of Twig 1.8, you can set the escaping strategy to use (``html``, ``js``,
133 As of Twig 1.9, you can set the escaping strategy to use (``css``, ``url``,
138 As of Twig 1.17, the ``filename`` escaping strategy (renamed to ``name`` as
139 of Twig 1.27) determines the escaping strategy to use for a template based on
159 future reuse. It speeds up Twig a lot as templates are only compiled once; and
161 See the ``cache`` and ``auto_reload`` options of ``\Twig\Environment`` above
167 Here is a list of the built-in loaders Twig provides:
169 ``\Twig\Loader\FilesystemLoader``
173 The ``prependPath()`` and support for namespaces were added in Twig 1.10.
176 Relative paths support was added in Twig 1.27.
178 ``\Twig\Loader\FilesystemLoader`` loads templates from the file system. This loader
182 $loader = new \Twig\Loader\FilesystemLoader($templateDir);
186 $loader = new \Twig\Loader\FilesystemLoader([$templateDir1, $templateDir2]);
188 With such a configuration, Twig will first look for templates in
212 ``\Twig\Loader\FilesystemLoader`` support absolute and relative paths. Using relative
217 $loader = new \Twig\Loader\FilesystemLoader('templates', getcwd().'/..');
221 When not passing the root path as a second argument, Twig uses ``getcwd()``
224 ``\Twig\Loader\ArrayLoader``
227 ``\Twig\Loader\ArrayLoader`` loads a template from a PHP array. It's passed an array
230 $loader = new \Twig\Loader\ArrayLoader([
233 $twig = new \Twig\Environment($loader);
248 ``\Twig\Loader\ChainLoader``
251 ``\Twig\Loader\ChainLoader`` delegates the loading of templates to other loaders::
253 $loader1 = new \Twig\Loader\ArrayLoader([
256 $loader2 = new \Twig\Loader\ArrayLoader([
261 $loader = new \Twig\Loader\ChainLoader([$loader1, $loader2]);
263 $twig = new \Twig\Environment($loader);
265 When looking for a template, Twig will try each loader in turn and it will
267 template from the above example, Twig will load it with ``$loader2`` but the
270 ``\Twig\Loader\ChainLoader`` accepts any loader that implements
271 ``\Twig\Loader\LoaderInterface``.
280 All loaders implement the ``\Twig\Loader\LoaderInterface``::
291 …* @deprecated since 1.27 (to be removed in 2.0), implement \Twig\Loader\SourceContextLoaderInterfa…
318 As of Twig 1.27, you should also implement
319 ``\Twig\Loader\SourceContextLoaderInterface`` to avoid deprecation notices.
323 As of Twig 1.11.0, you can also implement ``\Twig\Loader\ExistsLoaderInterface``
329 Twig extensions are packages that add new features to Twig. Using an
332 $twig->addExtension(new \Twig\Extension\SandboxExtension());
334 Twig comes bundled with the following extensions:
336 * *Twig_Extension_Core*: Defines all the core features of Twig.
341 * *Twig_Extension_Sandbox*: Adds a sandbox mode to the default Twig
344 * *Twig_Extension_Profiler*: Enabled the built-in Twig profiler (as of Twig
350 Twig environment, as they are registered by default.
359 Read the chapter about extending Twig to learn how to create your own
365 The ``core`` extension defines all the core features of Twig:
375 The ``escaper`` extension adds automatic output escaping to Twig. It defines a
381 $escaper = new \Twig\Extension\EscaperExtension('html');
393 Twig 1.8):
414 {{ "Twig<br />" }} {# won't be escaped #}
416 {% set text = "Twig<br />" %}
424 {{ foo ? "Twig<br />" : "<br />Twig" }} {# won't be escaped #}
426 {% set text = "Twig<br />" %}
427 {{ foo ? text : "<br />Twig" }} {# will be escaped #}
429 {% set text = "Twig<br />" %}
430 {{ foo ? text|raw : "<br />Twig" }} {# won't be escaped #}
432 {% set text = "Twig<br />" %}
433 {{ foo ? text|escape : "<br />Twig" }} {# the result of the expression won't be escaped #}
475 by a policy instance. By default, Twig comes with one policy class:
476 ``\Twig\Sandbox\SecurityPolicy``. This class allows you to white-list some
488 $policy = new \Twig\Sandbox\SecurityPolicy($tags, $filters, $methods, $properties, $functions);
494 won't be allowed and will generate a ``\Twig\Sandbox\SecurityError`` exception.
498 $sandbox = new \Twig\Extension\SandboxExtension($policy);
513 $sandbox = new \Twig\Extension\SandboxExtension($policy, true);
519 The Profile extension was added in Twig 1.18.
521 The ``profiler`` extension enables a profiler for Twig templates; it should
524 $profile = new \Twig\Profiler\Profile();
525 $twig->addExtension(new \Twig\Extension\ProfilerExtension($profile));
527 $dumper = new \Twig\Profiler\Dumper\TextDumper();
536 $dumper = new \Twig\Profiler\Dumper\BlackfireDumper();
551 $twig->addExtension(new \Twig\Extension\OptimizerExtension());
556 …$optimizer = new \Twig\Extension\OptimizerExtension(\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMI…
560 Twig supports the following optimizations:
562 * ``\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_ALL``, enables all optimizations
564 * ``\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_NONE``, disables all optimizations.
567 * ``\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_FOR``, optimizes the ``for`` tag by
569 * ``\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_RAW_FILTER``, removes the ``raw``
571 * ``\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_VAR_ACCESS``, simplifies the creation
577 Twig can throw exceptions:
579 * ``\Twig\Error\Error``: The base exception for all errors.
581 * ``\Twig\Error\SyntaxError``: Thrown to tell the user that there is a problem with
584 * ``\Twig\Error\RuntimeError``: Thrown when an error occurs at runtime (when a filter
587 * ``\Twig\Error\LoaderError``: Thrown when an error occurs during template loading.
589 * ``\Twig\Sandbox\SecurityError``: Thrown when an unallowed tag, filter, or