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',
]);

Notice that the second argument of the environment is an array of options.
The ``cache`` option is a compilation cache directory, where Twig caches
the compiled templates to avoid the parsing phase for subsequent
requests. It is very different from the cache you might want to add for
the evaluated templates. For such a need, you can use any available PHP
cache library.

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

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

The ``display()`` method is a shortcut to output the rendered template.

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

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

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

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

The ``stream()`` and ``streamBlock()`` methods return an iterable.

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

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.

Built-in Loaders
~~~~~~~~~~~~~~~~

Here is a list of the built-in loaders:

``\Twig\Loader\FilesystemLoader``
.................................

``\Twig\Loader\FilesystemLoader`` 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\FilesystemLoader($templateDir);

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

    $loader = new \Twig\Loader\FilesystemLoader([$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``.

You can add or prepend paths via the ``addPath()`` and ``prependPath()``
methods::

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

The filesystem loader also supports namespaced templates. This allows you to group
your templates under different namespaces which have their own template paths.

When using the ``setPaths()``, ``addPath()``, and ``prependPath()`` methods,
specify the namespace as the second argument (when not specified, these
methods act on the "main" namespace)::

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

Namespaced templates can be accessed via the special
``@namespace_name/template_path`` notation::

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

``\Twig\Loader\FilesystemLoader`` supports absolute and relative paths. Using relative
paths is preferred as it makes the cache keys independent of the project root
directory (for instance, it allows warming the cache from a build server where
the directory might be different from the one used on production servers)::

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

.. note::

    When not passing the root path as a second argument, Twig uses ``getcwd()``
    for relative paths.

``\Twig\Loader\ArrayLoader``
............................

``\Twig\Loader\ArrayLoader`` loads a template from a PHP array. It is passed an
array of strings bound to template names::

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

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

This loader is very useful for unit testing. It can also be used for small
projects where storing all templates in a single PHP file might make sense.

.. tip::

    When using the ``Array`` loader with a cache mechanism, you should know that
    a new cache key is generated each time a template content "changes" (the
    cache key being the source code of the template). If you don't want to see
    your cache grows out of control, you need to take care of clearing the old
    cache file by yourself.

``\Twig\Loader\ChainLoader``
............................

``\Twig\Loader\ChainLoader`` delegates the loading of templates to other loaders::

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

When looking for a template, Twig tries each loader in turn and returns as soon
as the template is found. When rendering the ``index.html.twig`` template from the
above example, Twig will load it with ``$loader2`` but the ``base.html.twig``
template will be loaded from ``$loader1``.

.. note::

    You can also add loaders via the ``addLoader()`` method.

Create your own Loader

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

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

Read the chapter about :doc:`extending Twig <advanced>` to learn how to
create your own extensions.

The ``core`` extension defines all the core features of Twig:

* :doc:`Tags <tags/index>`;
* :doc:`Filters <filters/index>`;
* :doc:`Functions <functions/index>`;
* :doc:`Tests <tests/index>`.

Escaper Extension

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

{{ article.to_html|raw }}

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

The ``autoescape`` tag has no effect on included files.

    {% set text = "Twig

    {% set text = "Twig

    {% set text = "Twig

Note that autoescaping has some limitations as escaping is applied on
expressions after evaluation. For instance, when working with
concatenation, ``{{ value|raw ~ other }}`` won't give the expected result
as escaping is applied on the result of the concatenation, not on the
individual variables (so, the ``raw`` filter won't have any effect here).

The ``sandbox`` extension can be used to evaluate untrusted code. Read more
about it in the :doc:`sandbox` chapter.

Profiler Extension

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

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

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

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

The ``optimizer`` extension optimizes the node tree before compilation::

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

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\OptimizerExtension(\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_FOR);

    $twig->addExtension($optimizer);

Twig supports the following optimizations:

* ``\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_ALL``, enables all optimizations
  (this is the default value).

* ``\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_NONE``, disables all optimizations.
  This reduces the compilation time, but it can increase the execution time
  and the consumed memory.

* ``\Twig\NodeVisitor\OptimizerNodeVisitor::OPTIMIZE_FOR``, optimizes the ``for`` tag by
  removing the ``loop`` variable creation whenever possible.

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.