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:

• Twig_Loader_Filesystem: Loads templates from the file system. This loader can find templates in folders on the file system and is the preferred way to load them:

  $loader = new Twig_Loader_Filesystem($templateDir);
  

  It can also look for templates in an array of directories:

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

  With such a configuration, Twig will first look for templates in $templateDir1 and if they do not exist, it will fallback to look for them in the $templateDir2.

• Twig_Loader_String: Loads templates from a string. It's a dummy loader as you pass it the source code directly:

  $loader = new Twig_Loader_String();
  

• Twig_Loader_Array: Loads a template from a PHP array. It's passed an array of strings bound to template names. This loader is useful for unit testing:

  $loader = new Twig_Loader_Array($templates);
  

Create your own Loader¶

All loaders implement the Twig_LoaderInterface:

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
     */
    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);
}

As an example, here is how the built-in Twig_Loader_String reads:

class Twig_Loader_String implements Twig_LoaderInterface
{
    public function getSource($name)
    {
      return $name;
    }

    public function getCacheKey($name)
    {
      return $name;
    }

    public function isFresh($name, $time)
    {
      return false;
    }
}

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:
  • for
  • if
  • extends
  • include
  • block
  • filter
  • macro
  • import
  • from
  • set
  • spaceless
• Filters:
  • date
  • format
  • replace
  • url_encode
  • json_encode
  • title
  • capitalize
  • upper
  • lower
  • striptags
  • join
  • reverse
  • length
  • sort
  • merge
  • default
  • keys
  • escape
  • e
• Functions:
  • range
  • constant
  • cycle
  • parent
  • block
• Tests:
  • even
  • odd
  • defined
  • sameas
  • null
  • divisibleby
  • constant
  • empty

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(true);
$twig->addExtension($escaper);

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

{{ 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):

{% 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:

  {{ "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:

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

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

  {{ 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). escaper and escaper('html') are marked safe for html, escaper('js') is marked safe for javascript, raw is marked safe for everything.

  {% autoescape true 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:

$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:

{% 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);

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);