Extending Twig

Charset-aware Filters

If you want to access the default charset in your filter, set the needs_charset option to true; Twig will pass the default charset as the first argument to the filter call:

1
2
3

$filter = new \Twig\TwigFilter('rot13', function (string $charset, $string) {
    return str_rot13($string);
}, ['needs_charset' => true]);

Environment-aware Filters

If you want to access the current environment instance in your filter, set the needs_environment option to true; Twig will pass the current environment as the first argument to the filter call:

1
2
3
4
5
6

$filter = new \Twig\TwigFilter('rot13', function (\Twig\Environment $env, $string) {
    // get the current charset for instance
    $charset = $env->getCharset();

    return str_rot13($string);
}, ['needs_environment' => true]);

Context-aware Filters

If you want to access the current context in your filter, set the needs_context option to true; Twig will pass the current context as the first argument to the filter call (or the second one if needs_environment is also set to true):

1
2
3
4
5
6
7

$filter = new \Twig\TwigFilter('rot13', function ($context, $string) {
    // ...
}, ['needs_context' => true]);

$filter = new \Twig\TwigFilter('rot13', function (\Twig\Environment $env, $context, $string) {
    // ...
}, ['needs_context' => true, 'needs_environment' => true]);

Automatic Escaping

If automatic escaping is enabled, the output of the filter may be escaped before printing. If your filter acts as an escaper (or explicitly outputs HTML or JavaScript code), you will want the raw output to be printed. In such a case, set the is_safe option:

1

$filter = new \Twig\TwigFilter('nl2br', 'nl2br', ['is_safe' => ['html']]);

Some filters may need to work on input that is already escaped or safe, for example when adding (safe) HTML tags to originally unsafe output. In such a case, set the pre_escape option to escape the input data before it is run through your filter:

1

$filter = new \Twig\TwigFilter('somefilter', 'somefilter', ['pre_escape' => 'html', 'is_safe' => ['html']]);

Variadic Filters

When a filter should accept an arbitrary number of arguments, set the is_variadic option to true; Twig will pass the extra arguments as the last argument to the filter call as an array:

1
2
3

$filter = new \Twig\TwigFilter('thumbnail', function ($file, array $options = []) {
    // ...
}, ['is_variadic' => true]);

Be warned that named arguments passed to a variadic filter cannot be checked for validity as they will automatically end up in the option array.

Dynamic Filters

A filter name containing the special * character is a dynamic filter and the * part will match any string:

1
2
3

$filter = new \Twig\TwigFilter('*_path', function ($name, $arguments) {
    // ...
});

The following filters are matched by the above defined dynamic filter:

• product_path
• category_path

A dynamic filter can define more than one dynamic parts:

1
2
3

$filter = new \Twig\TwigFilter('*_path_*', function ($name, $suffix, $arguments) {
    // ...
});

The filter receives all dynamic part values before the normal filter arguments, but after the environment and the context. For instance, a call to 'Paris'|a_path_b() will result in the following arguments to be passed to the filter: ('a', 'b', 'Paris').

Deprecated Filters

You can mark a filter as being deprecated by setting the deprecation_info option:

1
2
3

$filter = new \Twig\TwigFilter('obsolete', function () {
    // ...
}, ['deprecation_info' => new DeprecatedCallableInfo('twig/twig', '3.11', 'new_one')]);

The DeprecatedCallableInfo constructor takes the following parameters:

• The Composer package name that defines the filter;
• The version when the filter was deprecated.

Optionally, you can also provide the following parameters about an alternative:

• The package name that contains the alternative filter;
• The alternative filter name that replaces the deprecated one;
• The package version that added the alternative filter.

When a filter is deprecated, Twig emits a deprecation notice when compiling a template using it. See Recipes for more information.

1
2
3

$filter = new \Twig\TwigFilter('obsolete', function () {
    // ...
}, ['deprecated' => true, 'alternative' => 'new_one']);

1
2
3

$filter = new \Twig\TwigFilter('obsolete', function () {
    // ...
}, ['deprecated' => '1.1', 'deprecating_package' => 'twig/some-package']);

Registering a new tag

Add a tag by calling the addTokenParser method on the \Twig\Environment instance:

1
2

$twig = new \Twig\Environment($loader);
$twig->addTokenParser(new CustomSetTokenParser());

Defining a Token Parser

Now, let's see the actual code of this class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

class CustomSetTokenParser extends \Twig\TokenParser\AbstractTokenParser
{
    public function parse(\Twig\Token $token)
    {
        $parser = $this->parser;
        $stream = $parser->getStream();

        $name = $stream->expect(\Twig\Token::NAME_TYPE)->getValue();
        $stream->expect(\Twig\Token::OPERATOR_TYPE, '=');
        $value = $parser->getExpressionParser()->parseExpression();
        $stream->expect(\Twig\Token::BLOCK_END_TYPE);

        return new CustomSetNode($name, $value, $token->getLine());
    }

    public function getTag()
    {
        return 'set';
    }
}

The getTag() method must return the tag we want to parse, here set.

The parse() method is invoked whenever the parser encounters a set tag. It should return a \Twig\Node\Node instance that represents the node (the CustomSetNode calls creating is explained in the next section).

The parsing process is simplified thanks to a bunch of methods you can call from the token stream ($this->parser->getStream()):

• getCurrent(): Gets the current token in the stream.
• next(): Moves to the next token in the stream, but returns the old one.
• test($type), test($value) or test($type, $value): Determines whether the current token is of a particular type or value (or both). The value may be an array of several possible values.
• expect($type[, $value[, $message]]): If the current token isn't of the given type/value a syntax error is thrown. Otherwise, if the type and value are correct, the token is returned and the stream moves to the next token.
• look(): Looks at the next token without consuming it.

Parsing expressions is done by calling the parseExpression() like we did for the set tag.

Defining a Node

The CustomSetNode class itself is quite short:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class CustomSetNode extends \Twig\Node\Node
{
    public function __construct($name, \Twig\Node\Expression\AbstractExpression $value, $line)
    {
        parent::__construct(['value' => $value], ['name' => $name], $line);
    }

    public function compile(\Twig\Compiler $compiler)
    {
        $compiler
            ->addDebugInfo($this)
            ->write('$context[\''.$this->getAttribute('name').'\'] = ')
            ->subcompile($this->getNode('value'))
            ->raw(";\n")
        ;
    }
}

The compiler implements a fluid interface and provides methods that help the developer generate beautiful and readable PHP code:

• subcompile(): Compiles a node.
• raw(): Writes the given string as is.
• write(): Writes the given string by adding indentation at the beginning of each line.
• string(): Writes a quoted string.
• repr(): Writes a PHP representation of a given value (see \Twig\Node\ForNode for a usage example).
• addDebugInfo(): Adds the line of the original template file related to the current node as a comment.
• indent(): Indents the generated code (see \Twig\Node\BlockNode for a usage example).
• outdent(): Outdents the generated code (see \Twig\Node\BlockNode for a usage example).

Globals

Global variables can be registered in an extension via the getGlobals() method:

1
2
3
4
5
6
7
8
9
10
11

class CustomTwigExtension extends \Twig\Extension\AbstractExtension implements \Twig\Extension\GlobalsInterface
{
    public function getGlobals(): array
    {
        return [
            'text' => new Text(),
        ];
    }

    // ...
}

Functions

Functions can be registered in an extension via the getFunctions() method:

1
2
3
4
5
6
7
8
9
10
11

class CustomTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getFunctions()
    {
        return [
            new \Twig\TwigFunction('lipsum', 'generate_lipsum'),
        ];
    }

    // ...
}

Filters

To add a filter to an extension, you need to override the getFilters() method. This method must return an array of filters to add to the Twig environment:

1
2
3
4
5
6
7
8
9
10
11

class CustomTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getFilters()
    {
        return [
            new \Twig\TwigFilter('rot13', 'str_rot13'),
        ];
    }

    // ...
}

Tags

Adding a tag in an extension can be done by overriding the getTokenParsers() method. This method must return an array of tags to add to the Twig environment:

1
2
3
4
5
6
7
8
9

class CustomTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getTokenParsers()
    {
        return [new CustomSetTokenParser()];
    }

    // ...
}

In the above code, we have added a single new tag, defined by the CustomSetTokenParser class. The CustomSetTokenParser class is responsible for parsing the tag and compiling it to PHP.

Operators

The getOperators() methods lets you add new operators. Here is how to add the !, ||, and && operators:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class CustomTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getOperators()
    {
        return [
            [
                '!' => ['precedence' => 50, 'class' => \Twig\Node\Expression\Unary\NotUnary::class],
            ],
            [
                '||' => ['precedence' => 10, 'class' => \Twig\Node\Expression\Binary\OrBinary::class, 'associativity' => \Twig\ExpressionParser::OPERATOR_LEFT],
                '&&' => ['precedence' => 15, 'class' => \Twig\Node\Expression\Binary\AndBinary::class, 'associativity' => \Twig\ExpressionParser::OPERATOR_LEFT],
            ],
        ];
    }

    // ...
}

Tests

The getTests() method lets you add new test functions:

1
2
3
4
5
6
7
8
9
10
11

class CustomTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getTests()
    {
        return [
            new \Twig\TwigTest('even', 'twig_test_even'),
        ];
    }

    // ...
}

Definition vs Runtime

Twig filters, functions, and tests runtime implementations can be defined as any valid PHP callable:

• functions/static methods: Simple to implement and fast (used by all Twig core extensions); but it is hard for the runtime to depend on external objects;
• closures: Simple to implement;
• object methods: More flexible and required if your runtime code depends on external objects.

The simplest way to use methods is to define them on the extension itself:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

class CustomTwigExtension extends \Twig\Extension\AbstractExtension
{
    private $rot13Provider;

    public function __construct($rot13Provider)
    {
        $this->rot13Provider = $rot13Provider;
    }

    public function getFunctions()
    {
        return [
            new \Twig\TwigFunction('rot13', [$this, 'rot13']),
        ];
    }

    public function rot13($value)
    {
        return $this->rot13Provider->rot13($value);
    }
}

This is very convenient but not recommended as it makes template compilation depend on runtime dependencies even if they are not needed (think for instance as a dependency that connects to a database engine).

You can decouple the extension definitions from their runtime implementations by registering a \Twig\RuntimeLoader\RuntimeLoaderInterface instance on the environment that knows how to instantiate such runtime classes (runtime classes must be autoload-able):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class RuntimeLoader implements \Twig\RuntimeLoader\RuntimeLoaderInterface
{
    public function load($class)
    {
        // implement the logic to create an instance of $class
        // and inject its dependencies
        // most of the time, it means using your dependency injection container
        if ('CustomRuntimeExtension' === $class) {
            return new $class(new Rot13Provider());
        } else {
            // ...
        }
    }
}

$twig->addRuntimeLoader(new RuntimeLoader());

It is now possible to move the runtime logic to a new CustomRuntimeExtension class and use it directly in the extension:

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

class CustomRuntimeExtension
{
    private $rot13Provider;

    public function __construct($rot13Provider)
    {
        $this->rot13Provider = $rot13Provider;
    }

    public function rot13($value)
    {
        return $this->rot13Provider->rot13($value);
    }
}

class CustomTwigExtension extends \Twig\Extension\AbstractExtension
{
    public function getFunctions()
    {
        return [
            new \Twig\TwigFunction('rot13', ['CustomRuntimeExtension', 'rot13']),
            // or
            new \Twig\TwigFunction('rot13', 'CustomRuntimeExtension::rot13'),
        ];
    }
}

Functional Tests

You can create functional tests for extensions by creating the following file structure in your test directory:

1
2
3
4
5
6
7
8
9
10
11

Fixtures/
    filters/
        lower.test
        upper.test
    functions/
        date.test
        format.test
    tags/
        for.test
        if.test
IntegrationTest.php

The IntegrationTest.php file should look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

namespace Project\Tests;

use Twig\Test\IntegrationTestCase;

class IntegrationTest extends IntegrationTestCase
{
    public function getExtensions()
    {
        return [
            new CustomTwigExtension1(),
            new CustomTwigExtension2(),
        ];
    }

    public function getFixturesDir()
    {
        return __DIR__.'/Fixtures/';
    }
}

Fixtures examples can be found within the Twig repository tests/Twig/Fixtures directory.

Node Tests

Testing the node visitors can be complex, so extend your test cases from \Twig\Test\NodeTestCase. Examples can be found in the Twig repository tests/Twig/Node directory.