Compilation Cache¶

All template loaders can cache the compiled templates on the filesystem for future reuse. It speeds up Twig a lot as templates are only compiled once; and the performance boost is even larger if you use a PHP accelerator such as APC. See the cache and auto_reload options of Twig_Environment above for more information.

Built-in Loaders¶

Here is a list of the built-in loaders Twig provides:

$loader = new Twig_Loader_Filesystem($templateDir);

$loader = new Twig_Loader_Filesystem(array($templateDir1, $templateDir2));

$loader->addPath($templateDir3);
$loader->prependPath($templateDir4);

$loader->addPath($templateDir, 'admin');

$twig->render('@admin/index.html', array());

$loader = new Twig_Loader_Filesystem('templates', getcwd().'/..');

1
2
3
4
5
6

$loader = new Twig_Loader_Array(array(
    'index.html' => 'Hello {{ name }}!',
));
$twig = new Twig_Environment($loader);

echo $twig->render('index.html', array('name' => 'Fabien'));

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$loader1 = new Twig_Loader_Array(array(
    'base.html' => '{% block content %}{% endblock %}',
));
$loader2 = new Twig_Loader_Array(array(
    'index.html' => '{% extends "base.html" %}{% block content %}Hello {{ name }}{% endblock %}',
    'base.html'  => 'Will never be loaded',
));

$loader = new Twig_Loader_Chain(array($loader1, $loader2));

$twig = new Twig_Environment($loader);

Create your own Loader¶

All loaders implement the Twig_LoaderInterface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

interface Twig_LoaderInterface
{
    /**
     * Gets the source code of a template, given its name.
     *
     * @param  string $name string The name of the template to load
     *
     * @return string The template source code
     *
     * @deprecated since 1.27 (to be removed in 2.0), implement Twig_SourceContextLoaderInterface
     */
    function getSource($name);

    /**
     * Gets the cache key to use for the cache for a given template name.
     *
     * @param  string $name string The name of the template to load
     *
     * @return string The cache key
     */
    function getCacheKey($name);

    /**
     * Returns true if the template is still fresh.
     *
     * @param string    $name The template name
     * @param timestamp $time The last modification time of the cached template
     */
    function isFresh($name, $time);
}

The isFresh() method must return true if the current cached template is still fresh, given the last modification time, or false otherwise.

Core Extension¶

The core extension defines all the core features of Twig:

• Tags;
• Filters;
• Functions;
• Tests.

Escaper Extension¶

The escaper extension adds automatic output escaping to Twig. It defines a tag, autoescape, and a filter, raw.

When creating the escaper extension, you can switch on or off the global output escaping strategy:

$escaper = new Twig_Extension_Escaper('html');
$twig->addExtension($escaper);

If set to html, all variables in templates are escaped (using the html escaping strategy), except those using the raw filter:

1

{{ article.to_html|raw }}

You can also change the escaping mode locally by using the autoescape tag (see the autoescape doc for the syntax used before Twig 1.8):

1
2
3
4
5

{% autoescape 'html' %}
    {{ var }}
    {{ var|raw }}      {# var won't be escaped #}
    {{ var|escape }}   {# var won't be double-escaped #}
{% endautoescape %}

The escaping rules are implemented as follows:

• Literals (integers, booleans, arrays, ...) used in the template directly as variables or filter arguments are never automatically escaped:

  1 2 3 4

  {{ "Twig<br />" }} {# won't be escaped #} {% set text = "Twig<br />" %} {{ text }} {# will be escaped #}

• Expressions which the result is always a literal or a variable marked safe are never automatically escaped:

  {{ foo ? "Twig<br />" : "<br />Twig" }} {# won't be escaped #}
  
  {% set text = "Twig<br />" %}
  {{ foo ? text : "<br />Twig" }} {# will be escaped #}
  
  {% set text = "Twig<br />" %}
  {{ foo ? text|raw : "<br />Twig" }} {# won't be escaped #}
  
  {% set text = "Twig<br />" %}
  {{ foo ? text|escape : "<br />Twig" }} {# the result of the expression won't be escaped #}

• Escaping is applied before printing, after any other filter is applied:

  1	{{ var|upper }} {# is equivalent to {{ var|upper|escape }} #}

• The raw filter should only be used at the end of the filter chain:

  1 2 3

  {{ var|raw|upper }} {# will be escaped #} {{ var|upper|raw }} {# won't be escaped #}

• Automatic escaping is not applied if the last filter in the chain is marked safe for the current context (e.g. html or js). escape and escape('html') are marked safe for HTML, escape('js') is marked safe for JavaScript, raw is marked safe for everything.

  1 2 3 4 5

  {% autoescape 'js' %} {{ var|escape('html') }} {# will be escaped for HTML and JavaScript #} {{ var }} {# will be escaped for JavaScript #} {{ var|escape('js') }} {# won't be double-escaped #} {% endautoescape %}

Sandbox Extension¶

The sandbox extension can be used to evaluate untrusted code. Access to unsafe attributes and methods is prohibited. The sandbox security is managed by a policy instance. By default, Twig comes with one policy class: Twig_Sandbox_SecurityPolicy. This class allows you to white-list some tags, filters, properties, and methods:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$tags = array('if');
$filters = array('upper');
$methods = array(
    'Article' => array('getTitle', 'getBody'),
);
$properties = array(
    'Article' => array('title', 'body'),
);
$functions = array('range');
$policy = new Twig_Sandbox_SecurityPolicy($tags, $filters, $methods, $properties, $functions);

With the previous configuration, the security policy will only allow usage of the if tag, and the upper filter. Moreover, the templates will only be able to call the getTitle() and getBody() methods on Article objects, and the title and body public properties. Everything else won't be allowed and will generate a Twig_Sandbox_SecurityError exception.

The policy object is the first argument of the sandbox constructor:

$sandbox = new Twig_Extension_Sandbox($policy);
$twig->addExtension($sandbox);

By default, the sandbox mode is disabled and should be enabled when including untrusted template code by using the sandbox tag:

1
2
3

{% sandbox %}
    {% include 'user.html' %}
{% endsandbox %}

You can sandbox all templates by passing true as the second argument of the extension constructor:

$sandbox = new Twig_Extension_Sandbox($policy, true);

Profiler Extension¶

New in version 1.18: The Profile extension was added in Twig 1.18.

The profiler extension enables a profiler for Twig templates; it should only be used on your development machines as it adds some overhead:

1
2
3
4
5

$profile = new Twig_Profiler_Profile();
$twig->addExtension(new Twig_Extension_Profiler($profile));

$dumper = new Twig_Profiler_Dumper_Text();
echo $dumper->dump($profile);

A profile contains information about time and memory consumption for template, block, and macro executions.

You can also dump the data in a Blackfire.io compatible format:

$dumper = new Twig_Profiler_Dumper_Blackfire();
file_put_contents('/path/to/profile.prof', $dumper->dump($profile));

Upload the profile to visualize it (create a free account first):

1

blackfire --slot=7 upload /path/to/profile.prof

Optimizer Extension¶

The optimizer extension optimizes the node tree before compilation:

$twig->addExtension(new Twig_Extension_Optimizer());

By default, all optimizations are turned on. You can select the ones you want to enable by passing them to the constructor:

$optimizer = new Twig_Extension_Optimizer(Twig_NodeVisitor_Optimizer::OPTIMIZE_FOR);

$twig->addExtension($optimizer);

Twig supports the following optimizations:

• Twig_NodeVisitor_Optimizer::OPTIMIZE_ALL, enables all optimizations (this is the default value).
• Twig_NodeVisitor_Optimizer::OPTIMIZE_NONE, disables all optimizations. This reduces the compilation time, but it can increase the execution time and the consumed memory.
• Twig_NodeVisitor_Optimizer::OPTIMIZE_FOR, optimizes the for tag by removing the loop variable creation whenever possible.
• Twig_NodeVisitor_Optimizer::OPTIMIZE_RAW_FILTER, removes the raw filter whenever possible.
• Twig_NodeVisitor_Optimizer::OPTIMIZE_VAR_ACCESS, simplifies the creation and access of variables in the compiled templates whenever possible.