doc/recipes.rst
a855b189
 Recipes
 =======
 
bd87ba8a
 .. _deprecation-notices:
 
 Displaying Deprecation Notices
 ------------------------------
 
 Deprecated features generate deprecation notices (via a call to the
56c73827
 ``trigger_error()`` PHP function). By default, they are silenced and never
 displayed nor logged.
 
5ac239ca
 To remove all deprecated feature usages from your templates, write and run a
 script along the lines of the following::
56c73827
 
     require_once __DIR__.'/vendor/autoload.php';
 
     $twig = create_your_twig_env();
 
d1596b6c
     $deprecations = new \Twig\Util\DeprecationCollector($twig);
56c73827
 
     print_r($deprecations->collectDir(__DIR__.'/templates'));
 
 The ``collectDir()`` method compiles all templates found in a directory,
 catches deprecation notices, and return them.
 
 .. tip::
 
     If your templates are not stored on the filesystem, use the ``collect()``
236c1bdc
     method instead. ``collect()`` takes a ``Traversable`` which must return
56c73827
     template names as keys and template contents as values (as done by
d1596b6c
     ``\Twig\Util\TemplateDirIterator``).
56c73827
 
 However, this code won't find all deprecations (like using deprecated some Twig
 classes). To catch all notices, register a custom error handler like the one
 below::
bd87ba8a
 
a2c42534
     $deprecations = [];
bd87ba8a
     set_error_handler(function ($type, $msg) use (&$deprecations) {
         if (E_USER_DEPRECATED === $type) {
             $deprecations[] = $msg;
         }
     });
 
56c73827
     // run your application
bd87ba8a
 
     print_r($deprecations);
 
56c73827
 Note that most deprecation notices are triggered during **compilation**, so
 they won't be generated when templates are already cached.
bd87ba8a
 
 .. tip::
 
     If you want to manage the deprecation notices from your PHPUnit tests, have
     a look at the `symfony/phpunit-bridge
     <https://github.com/symfony/phpunit-bridge>`_ package, which eases the
5ac239ca
     process.
bd87ba8a
 
a855b189
 Making a Layout conditional
 ---------------------------
 
 Working with Ajax means that the same content is sometimes displayed as is,
 and sometimes decorated with a layout. As Twig layout template names can be
 any valid expression, you can pass a variable that evaluates to ``true`` when
 the request is made via Ajax and choose the layout accordingly:
 
fa836ddf
 .. code-block:: twig
a855b189
 
     {% extends request.ajax ? "base_ajax.html" : "base.html" %}
 
     {% block content %}
         This is the content to be displayed.
     {% endblock %}
 
 Making an Include dynamic
 -------------------------
 
 When including a template, its name does not need to be a string. For
 instance, the name can depend on the value of a variable:
 
fa836ddf
 .. code-block:: twig
a855b189
 
     {% include var ~ '_foo.html' %}
 
 If ``var`` evaluates to ``index``, the ``index_foo.html`` template will be
 rendered.
 
 As a matter of fact, the template name can be any valid expression, such as
 the following:
 
fa836ddf
 .. code-block:: twig
a855b189
 
     {% include var|default('index') ~ '_foo.html' %}
 
fc4fe73f
 Overriding a Template that also extends itself
 ----------------------------------------------
 
 A template can be customized in two different ways:
 
 * *Inheritance*: A template *extends* a parent template and overrides some
   blocks;
 
 * *Replacement*: If you use the filesystem loader, Twig loads the first
65f09ac7
   template it finds in a list of configured directories; a template found in a
fc4fe73f
   directory *replaces* another one from a directory further in the list.
 
 But how do you combine both: *replace* a template that also extends itself
 (aka a template in a directory further in the list)?
 
 Let's say that your templates are loaded from both ``.../templates/mysite``
 and ``.../templates/default`` in this order. The ``page.twig`` template,
 stored in ``.../templates/default`` reads as follows:
 
fa836ddf
 .. code-block:: twig
fc4fe73f
 
     {# page.twig #}
     {% extends "layout.twig" %}
 
     {% block content %}
     {% endblock %}
 
 You can replace this template by putting a file with the same name in
 ``.../templates/mysite``. And if you want to extend the original template, you
 might be tempted to write the following:
 
fa836ddf
 .. code-block:: twig
fc4fe73f
 
     {# page.twig in .../templates/mysite #}
     {% extends "page.twig" %} {# from .../templates/default #}
 
 Of course, this will not work as Twig will always load the template from
 ``.../templates/mysite``.
 
 It turns out it is possible to get this to work, by adding a directory right
 at the end of your template directories, which is the parent of all of the
 other directories: ``.../templates`` in our case. This has the effect of
 making every template file within our system uniquely addressable. Most of the
 time you will use the "normal" paths, but in the special case of wanting to
 extend a template with an overriding version of itself we can reference its
 parent's full, unambiguous template path in the extends tag:
 
fa836ddf
 .. code-block:: twig
fc4fe73f
 
     {# page.twig in .../templates/mysite #}
     {% extends "default/page.twig" %} {# from .../templates #}
 
 .. note::
 
     This recipe was inspired by the following Django wiki page:
4f57c6ea
     https://code.djangoproject.com/wiki/ExtendingTemplates
fc4fe73f
 
a855b189
 Customizing the Syntax
 ----------------------
 
5ac239ca
 Twig allows some syntax customization for the block delimiters. It's **not**
a855b189
 recommended to use this feature as templates will be tied with your custom
 syntax. But for specific projects, it can make sense to change the defaults.
 
 To change the block delimiters, you need to create your own lexer object::
 
d1596b6c
     $twig = new \Twig\Environment(...);
a855b189
 
d1596b6c
     $lexer = new \Twig\Lexer($twig, [
a2c42534
         'tag_comment'   => ['{#', '#}'],
         'tag_block'     => ['{%', '%}'],
         'tag_variable'  => ['{{', '}}'],
         'interpolation' => ['#{', '}'],
     ]);
a855b189
     $twig->setLexer($lexer);
 
 Here are some configuration example that simulates some other template engines
 syntax::
 
     // Ruby erb syntax
d1596b6c
     $lexer = new \Twig\Lexer($twig, [
a2c42534
         'tag_comment'  => ['<%#', '%>'],
         'tag_block'    => ['<%', '%>'],
         'tag_variable' => ['<%=', '%>'],
     ]);
a855b189
 
     // SGML Comment Syntax
d1596b6c
     $lexer = new \Twig\Lexer($twig, [
a2c42534
         'tag_comment'  => ['<!--#', '-->'],
         'tag_block'    => ['<!--', '-->'],
         'tag_variable' => ['${', '}'],
     ]);
a855b189
 
     // Smarty like
d1596b6c
     $lexer = new \Twig\Lexer($twig, [
a2c42534
         'tag_comment'  => ['{*', '*}'],
         'tag_block'    => ['{', '}'],
         'tag_variable' => ['{$', '}'],
     ]);
a855b189
 
 Using dynamic Object Properties
 -------------------------------
 
 When Twig encounters a variable like ``article.title``, it tries to find a
 ``title`` public property in the ``article`` object.
 
 It also works if the property does not exist but is rather defined dynamically
5ac239ca
 thanks to the magic ``__get()`` method; you need to also implement the
a855b189
 ``__isset()`` magic method like shown in the following snippet of code::
 
     class Article
     {
         public function __get($name)
         {
3697ef4a
             if ('title' == $name) {
a855b189
                 return 'The title';
             }
 
             // throw some kind of error
         }
 
         public function __isset($name)
         {
3697ef4a
             if ('title' == $name) {
a855b189
                 return true;
             }
 
             return false;
         }
     }
 
 Accessing the parent Context in Nested Loops
 --------------------------------------------
 
 Sometimes, when using nested loops, you need to access the parent context. The
 parent context is always accessible via the ``loop.parent`` variable. For
 instance, if you have the following template data::
 
a2c42534
     $data = [
         'topics' => [
             'topic1' => ['Message 1 of topic 1', 'Message 2 of topic 1'],
             'topic2' => ['Message 1 of topic 2', 'Message 2 of topic 2'],
         ],
     ];
a855b189
 
 And the following template to display all messages in all topics:
 
fa836ddf
 .. code-block:: twig
a855b189
 
     {% for topic, messages in topics %}
         * {{ loop.index }}: {{ topic }}
       {% for message in messages %}
           - {{ loop.parent.loop.index }}.{{ loop.index }}: {{ message }}
       {% endfor %}
     {% endfor %}
 
 The output will be similar to:
 
 .. code-block:: text
 
     * 1: topic1
       - 1.1: The message 1 of topic 1
       - 1.2: The message 2 of topic 1
     * 2: topic2
       - 2.1: The message 1 of topic 2
       - 2.2: The message 2 of topic 2
 
 In the inner loop, the ``loop.parent`` variable is used to access the outer
 context. So, the index of the current ``topic`` defined in the outer for loop
 is accessible via the ``loop.parent.loop.index`` variable.
1f7d1423
 
e8fa22a4
 Defining undefined Functions and Filters on the Fly
 ---------------------------------------------------
1f7d1423
 
 When a function (or a filter) is not defined, Twig defaults to throw a
d1596b6c
 ``\Twig\Error\SyntaxError`` exception. However, it can also call a `callback`_ (any
1f7d1423
 valid PHP callable) which should return a function (or a filter).
 
34666d40
 For filters, register callbacks with ``registerUndefinedFilterCallback()``.
1f7d1423
 For functions, use ``registerUndefinedFunctionCallback()``::
 
     // auto-register all native PHP functions as Twig functions
     // don't try this at home as it's not secure at all!
     $twig->registerUndefinedFunctionCallback(function ($name) {
         if (function_exists($name)) {
69f37c16
             return new \Twig\TwigFunction($name, $name);
1f7d1423
         }
 
         return false;
     });
 
 If the callable is not able to return a valid function (or filter), it must
 return ``false``.
 
 If you register more than one callback, Twig will call them in turn until one
 does not return ``false``.
 
 .. tip::
 
     As the resolution of functions and filters is done during compilation,
     there is no overhead when registering these callbacks.
 
e8fa22a4
 Validating the Template Syntax
 ------------------------------
 
2511617f
 When template code is provided by a third-party (through a web interface for
e8fa22a4
 instance), it might be interesting to validate the template syntax before
 saving it. If the template code is stored in a `$template` variable, here is
0580f192
 how you can do it::
e8fa22a4
 
0580f192
     try {
d1596b6c
         $twig->parse($twig->tokenize(new \Twig\Source($template)));
e8fa22a4
 
0580f192
         // the $template is valid
d1596b6c
     } catch (\Twig\Error\SyntaxError $e) {
0580f192
         // $template contains one or more syntax errors
0451cfdd
     }
eb5c9fbc
 
fe3c17f5
 If you iterate over a set of files, you can pass the filename to the
 ``tokenize()`` method to get the filename in the exception message::
 
     foreach ($files as $file) {
         try {
d1596b6c
             $twig->parse($twig->tokenize(new \Twig\Source($template, $file->getFilename(), $file)));
fe3c17f5
 
             // the $template is valid
d1596b6c
         } catch (\Twig\Error\SyntaxError $e) {
fe3c17f5
             // $template contains one or more syntax errors
         }
     }
 
7ea15600
 .. note::
 
     This method won't catch any sandbox policy violations because the policy
     is enforced during template rendering (as Twig needs the context for some
     checks like allowed methods on objects).
 
1f3fb9a1
 Refreshing modified Templates when OPcache or APC is enabled
 ------------------------------------------------------------
eb5c9fbc
 
af129b2f
 When using OPcache with ``opcache.validate_timestamps`` set to ``0`` or APC
 with ``apc.stat`` set to ``0`` and Twig cache enabled, clearing the template
e9b08026
 cache won't update the cache.
eb5c9fbc
 
96a54b3f
 To get around this, force Twig to invalidate the bytecode cache::
e8fa22a4
 
d1596b6c
     $twig = new \Twig\Environment($loader, [
         'cache' => new \Twig\Cache\FilesystemCache('/some/cache/path', \Twig\Cache\FilesystemCache::FORCE_BYTECODE_INVALIDATION),
e9b08026
         // ...
a2c42534
     ]);
e8fa22a4
 
fa08e76f
 Reusing a stateful Node Visitor
 -------------------------------
 
d1596b6c
 When attaching a visitor to a ``\Twig\Environment`` instance, Twig uses it to
fa08e76f
 visit *all* templates it compiles. If you need to keep some state information
 around, you probably want to reset it when visiting a new template.
 
 This can be easily achieved with the following code::
 
a2c42534
     protected $someTemplateState = [];
fa08e76f
 
d1596b6c
     public function enterNode(\Twig\Node\Node $node, \Twig\Environment $env)
fa08e76f
     {
d1596b6c
         if ($node instanceof \Twig\Node\ModuleNode) {
fa08e76f
             // reset the state as we are entering a new template
a2c42534
             $this->someTemplateState = [];
fa08e76f
         }
 
         // ...
 
         return $node;
     }
 
0505c2fe
 Using a Database to store Templates
 -----------------------------------
 
 If you are developing a CMS, templates are usually stored in a database. This
 recipe gives you a simple PDO template loader you can use as a starting point
 for your own.
 
 First, let's create a temporary in-memory SQLite3 database to work with::
 
     $dbh = new PDO('sqlite::memory:');
     $dbh->exec('CREATE TABLE templates (name STRING, source STRING, last_modified INTEGER)');
     $base = '{% block content %}{% endblock %}';
     $index = '
     {% extends "base.twig" %}
     {% block content %}Hello {{ name }}{% endblock %}
     ';
     $now = time();
97d9dc04
     $dbh->prepare('INSERT INTO templates (name, source, last_modified) VALUES (?, ?, ?)')->execute(['base.twig', $base, $now]);
     $dbh->prepare('INSERT INTO templates (name, source, last_modified) VALUES (?, ?, ?)')->execute(['index.twig', $index, $now]);
0505c2fe
 
 We have created a simple ``templates`` table that hosts two templates:
 ``base.twig`` and ``index.twig``.
 
 Now, let's define a loader able to use this database::
 
d1596b6c
     class DatabaseTwigLoader implements \Twig\Loader\LoaderInterface
0505c2fe
     {
         protected $dbh;
 
         public function __construct(PDO $dbh)
         {
             $this->dbh = $dbh;
         }
 
21ecba8c
         public function getSourceContext($name)
0505c2fe
         {
             if (false === $source = $this->getValue('source', $name)) {
d1596b6c
                 throw new \Twig\Error\LoaderError(sprintf('Template "%s" does not exist.', $name));
0505c2fe
             }
 
d1596b6c
             return new \Twig\Source($source, $name);
0505c2fe
         }
 
         public function exists($name)
         {
             return $name === $this->getValue('name', $name);
         }
 
         public function getCacheKey($name)
         {
             return $name;
         }
 
         public function isFresh($name, $time)
         {
             if (false === $lastModified = $this->getValue('last_modified', $name)) {
                 return false;
             }
 
             return $lastModified <= $time;
         }
 
         protected function getValue($column, $name)
         {
             $sth = $this->dbh->prepare('SELECT '.$column.' FROM templates WHERE name = :name');
a2c42534
             $sth->execute([':name' => (string) $name]);
0505c2fe
 
             return $sth->fetchColumn();
         }
     }
 
 Finally, here is an example on how you can use it::
 
     $loader = new DatabaseTwigLoader($dbh);
d1596b6c
     $twig = new \Twig\Environment($loader);
0505c2fe
 
a2c42534
     echo $twig->render('index.twig', ['name' => 'Fabien']);
0505c2fe
 
 Using different Template Sources
 --------------------------------
 
 This recipe is the continuation of the previous one. Even if you store the
 contributed templates in a database, you might want to keep the original/base
 templates on the filesystem. When templates can be loaded from different
d1596b6c
 sources, you need to use the ``\Twig\Loader\ChainLoader`` loader.
0505c2fe
 
 As you can see in the previous recipe, we reference the template in the exact
 same way as we would have done it with a regular filesystem loader. This is
 the key to be able to mix and match templates coming from the database, the
 filesystem, or any other loader for that matter: the template name should be a
 logical name, and not the path from the filesystem::
 
     $loader1 = new DatabaseTwigLoader($dbh);
d1596b6c
     $loader2 = new \Twig\Loader\ArrayLoader([
0505c2fe
         'base.twig' => '{% block content %}{% endblock %}',
a2c42534
     ]);
d1596b6c
     $loader = new \Twig\Loader\ChainLoader([$loader1, $loader2]);
0505c2fe
 
d1596b6c
     $twig = new \Twig\Environment($loader);
0505c2fe
 
a2c42534
     echo $twig->render('index.twig', ['name' => 'Fabien']);
0505c2fe
 
 Now that the ``base.twig`` templates is defined in an array loader, you can
 remove it from the database, and everything else will still work as before.
 
77fed4e6
 Loading a Template from a String
 --------------------------------
 
 From a template, you can easily load a template stored in a string via the
d1596b6c
 ``template_from_string`` function (via the ``\Twig\Extension\StringLoaderExtension``
16cfb319
 extension):
4e58c481
 
fa836ddf
 .. code-block:: twig
4e58c481
 
     {{ include(template_from_string("Hello {{ name }}")) }}
 
77fed4e6
 From PHP, it's also possible to load a template stored in a string via
d1596b6c
 ``\Twig\Environment::createTemplate()``::
77fed4e6
 
     $template = $twig->createTemplate('hello {{ name }}');
a2c42534
     echo $template->render(['name' => 'Fabien']);
77fed4e6
 
b162a91e
 Using Twig and AngularJS in the same Templates
 ----------------------------------------------
 
 Mixing different template syntaxes in the same file is not a recommended
 practice as both AngularJS and Twig use the same delimiters in their syntax:
 ``{{`` and ``}}``.
 
 Still, if you want to use AngularJS and Twig in the same template, there are
 two ways to make it work depending on the amount of AngularJS you need to
 include in your templates:
 
 * Escaping the AngularJS delimiters by wrapping AngularJS sections with the
   ``{% verbatim %}`` tag or by escaping each delimiter via ``{{ '{{' }}`` and
   ``{{ '}}' }}``;
 
 * Changing the delimiters of one of the template engines (depending on which
   engine you introduced last):
 
   * For AngularJS, change the interpolation tags using the
     ``interpolateProvider`` service, for instance at the module initialization
     time:
 
adba4c2a
     ..  code-block:: javascript
629810c9
 
         angular.module('myApp', []).config(function($interpolateProvider) {
             $interpolateProvider.startSymbol('{[').endSymbol(']}');
         });
b162a91e
 
   * For Twig, change the delimiters via the ``tag_variable`` Lexer option:
 
adba4c2a
     ..  code-block:: php
629810c9
 
d1596b6c
         $env->setLexer(new \Twig\Lexer($env, [
a2c42534
             'tag_variable' => ['{[', ']}'],
         ]));
b162a91e
 
4f57c6ea
 .. _callback: https://secure.php.net/manual/en/function.is-callable.php