Twig for Developers

Basics

Twig uses a central object called the environment (of class \Twig\Environment). Instances of this class are used to store the configuration and extensions, and are used to load templates.

Most applications create one \Twig\Environment object on application initialization and use that to load templates. In some cases, it might be useful to have multiple environments side by side, with different configurations.

The typical way to configure Twig to load templates for an application looks roughly like this:

1
2
3
4
5
6

require_once '/path/to/vendor/autoload.php';

$loader = new \Twig\Loader\FilesystemLoader('/path/to/templates');
$twig = new \Twig\Environment($loader, [
    'cache' => '/path/to/compilation_cache',
]);

This creates a template environment with a default configuration and a loader that looks up templates in the /path/to/templates/ directory. Different loaders are available and you can also write your own if you want to load templates from a database or other resources.

Loading Templates

To load a template, call the load() method on a Twig environment which returns a \Twig\TemplateWrapper instance:

1

$template = $twig->load('index.html.twig');

Rendering Templates

To render a template with some variables, call the render() method:

1

echo $template->render(['the' => 'variables', 'go' => 'here']);

You can also load and render the template directly via the Environment:

1

echo $twig->render('index.html.twig', ['the' => 'variables', 'go' => 'here']);

If a template defines blocks, they can be rendered individually via the renderBlock() call:

1

echo $template->renderBlock('block_name', ['the' => 'variables', 'go' => 'here']);

Streaming Templates

To stream a template, call the stream() method`:

1

$template->stream(['the' => 'variables', 'go' => 'here']);

To stream a specific template block, call the streamBlock() method:

1

$template->streamBlock('block_name', ['the' => 'variables', 'go' => 'here']);

Environment Options

When creating a new \Twig\Environment instance, you can pass an array of options as the constructor second argument:

1

$twig = new \Twig\Environment($loader, ['debug' => true]);

The following options are available:

• debug boolean

  When set to true, the generated templates have a __toString() method that you can use to display the generated nodes (default to false).

• charset string (defaults to utf-8)

  The charset used by the templates.

• cache string or false

  An absolute path where to store the compiled templates, or false to disable caching (which is the default).

• auto_reload boolean

  When developing with Twig, it's useful to recompile the template whenever the source code changes. If you don't provide a value for the auto_reload option, it will be determined automatically based on the debug value.

• strict_variables boolean

  If set to false, Twig will silently ignore invalid variables (variables and or attributes/methods that do not exist) and replace them with a null value. When set to true, Twig throws an exception instead (default to false).

• autoescape string

  Sets the default auto-escaping strategy (name, html, js, css, url, html_attr, or a PHP callback that takes the template "filename" and returns the escaping strategy to use -- the callback cannot be a function name to avoid collision with built-in escaping strategies); set it to false to disable auto-escaping. The name escaping strategy determines the escaping strategy to use for a template based on the template filename extension (this strategy does not incur any overhead at runtime as auto-escaping is done at compilation time.)

• optimizations integer

  A flag that indicates which optimizations to apply (default to -1 -- all optimizations are enabled; set it to 0 to disable).

Loaders

Loaders are responsible for loading templates from a resource such as the file system.

1

$loader = new \Twig\Loader\FilesystemLoader($templateDir);

1

$loader = new \Twig\Loader\FilesystemLoader([$templateDir1, $templateDir2]);

1
2

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

1

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

1

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

1

$loader = new \Twig\Loader\FilesystemLoader('templates', getcwd().'/..');

1
2
3
4
5
6

$loader = new \Twig\Loader\ArrayLoader([
    'index.html.twig' => 'Hello {{ name }}!',
]);
$twig = new \Twig\Environment($loader);

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

1
2
3
4
5
6
7
8
9
10
11

$loader1 = new \Twig\Loader\ArrayLoader([
    'base.html.twig' => '{% block content %}{% endblock %}',
]);
$loader2 = new \Twig\Loader\ArrayLoader([
    'index.html.twig' => '{% extends "base.html.twig" %}{% block content %}Hello {{ name }}{% endblock %}',
    'base.html.twig'  => 'Will never be loaded',
]);

$loader = new \Twig\Loader\ChainLoader([$loader1, $loader2]);

$twig = new \Twig\Environment($loader);

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

interface \Twig\Loader\LoaderInterface
{
    /**
     * Returns the source context for a given template logical name.
     *
     * @param string $name The template logical name
     *
     * @return \Twig\Source
     *
     * @throws \Twig\Error\LoaderError When $name is not found
     */
    public function getSourceContext($name);

    /**
     * Gets the cache key to use for the cache for a given template name.
     *
     * @param string $name The name of the template to load
     *
     * @return string The cache key
     *
     * @throws \Twig\Error\LoaderError When $name is not found
     */
    public 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
     *
     * @return bool    true if the template is fresh, false otherwise
     *
     * @throws \Twig\Error\LoaderError When $name is not found
     */
    public function isFresh($name, $time);

    /**
     * Check if we have the source code of a template, given its name.
     *
     * @param string $name The name of the template to check if we can load
     *
     * @return bool    If the template source code is handled by this loader or not
     */
    public function exists($name);
}

Using Extensions

Twig extensions are packages that add new features to Twig. Register an extension via the addExtension() method:

1

$twig->addExtension(new \Twig\Extension\SandboxExtension());

Twig comes bundled with the following extensions:

• TwigExtensionCoreExtension: Defines all the core features of Twig.
• TwigExtensionDebugExtension: Defines the dump function to help debug template variables.
• TwigExtensionEscaperExtension: Adds automatic output-escaping and the possibility to escape/unescape blocks of code.
• TwigExtensionSandboxExtension: Adds a sandbox mode to the default Twig environment, making it safe to evaluate untrusted code.
• TwigExtensionProfilerExtension: Enables the built-in Twig profiler.
• TwigExtensionOptimizerExtension: Optimizes the node tree before compilation.

• TwigExtensionStringLoaderExtension: Defines the template_from_string

  function to allow loading templates from string in a template.

The Core, Escaper, and Optimizer extensions are registered by default.

Built-in Extensions

This section describes the features added by the built-in extensions.

1
2

$escaper = new \Twig\Extension\EscaperExtension('html');
$twig->addExtension($escaper);

1

{{ article.to_html|raw }}

1
2
3
4
5

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

1
2
3
4
5

$profile = new \Twig\Profiler\Profile();
$twig->addExtension(new \Twig\Extension\ProfilerExtension($profile));

$dumper = new \Twig\Profiler\Dumper\TextDumper();
echo $dumper->dump($profile);

1
2

$dumper = new \Twig\Profiler\Dumper\BlackfireDumper();
file_put_contents('/path/to/profile.prof', $dumper->dump($profile));

1

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

1

$twig->addExtension(new \Twig\Extension\OptimizerExtension());

1
2
3

$optimizer = new \Twig\Extension\OptimizerExtension(\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_FOR);

$twig->addExtension($optimizer);

Exceptions

Twig can throw exceptions:

• \Twig\Error\Error: The base exception for all errors.
• \Twig\Error\SyntaxError: Thrown to tell the user that there is a problem with the template syntax.
• \Twig\Error\RuntimeError: Thrown when an error occurs at runtime (when a filter does not exist for instance).
• \Twig\Error\LoaderError: Thrown when an error occurs during template loading.
• \Twig\Sandbox\SecurityError: Thrown when an unallowed tag, filter, or method is called in a sandboxed template.