Extending Twig ¶

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
  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 'foo'|a_path_b() will result in the following arguments to be passed to the filter: ('a', 'b', 'foo').

Deprecated Filters ¶

You can mark a filter as being deprecated by setting the deprecated option to true. You can also give an alternative filter that replaces the deprecated one when that makes sense:

1
2
3

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

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

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

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 Project_Set_TokenParser 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 Project_Set_Node($name, $value, $token->getLine(), $this->getTag());
    }

    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 Project_Set_Node 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.
  getCurrent(): ストリーム内の現在のトークンを取得します。
• next(): Moves to the next token in the stream, but returns the old one.
  next(): ストリーム内の次のトークンに移動しますが、古いトークンを返します。
• 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.
  test($type)、test($value) または test($type, $value): 現在のトークンが特定のタイプまたは値 (またはその両方) であるかどうかを判断します。値は、複数の可能な値の配列である場合があります。
• 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.
  expect($type[, $value[, $message]]): 現在のトークンが指定されたタイプ/値でない場合、構文エラーがスローされます。それ以外の場合、型と値が正しい場合、トークンが返され、ストリームは次のトークンに移動します。
• look(): Looks at the next token without consuming it.
  look(): 消費せずに次のトークンを調べます。

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

Defining a Node ¶

The Project_Set_Node class itself is quite short:

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

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

    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.
  subcompile(): ノードをコンパイルします。
• raw(): Writes the given string as is.
  raw(): 指定された文字列をそのまま書き込みます。
• write(): Writes the given string by adding indentation at the beginning of each line.
  write(): 各行の先頭にインデントを追加して、指定された文字列を書き込みます。
• string(): Writes a quoted string.
  string(): 引用符で囲まれた文字列を書き込みます。
• repr(): Writes a PHP representation of a given value (see \Twig\Node\ForNode for a usage example).
  repr(): 指定された値の PHP 表現を書き込みます (使用例については、\Twig\Node\ForNode を参照してください)。
• addDebugInfo(): Adds the line of the original template file related to the current node as a comment.
  addDebugInfo(): 現在のノードに関連する元のテンプレート ファイルの行をコメントとして追加します。
• indent(): Indents the generated code (see \Twig\Node\BlockNode for a usage example).
  indent(): 生成されたコードをインデントします (使用例については \Twig\Node\BlockNode を参照してください)。
• outdent(): Outdents the generated code (see \Twig\Node\BlockNode for a usage example).
  outdent(): 生成されたコードをアウトデントします (使用例については \Twig\Node\BlockNode を参照してください)。

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 Project_Twig_Extension 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 Project_Twig_Extension 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 Project_Twig_Extension 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 Project_Twig_Extension extends \Twig\Extension\AbstractExtension
{
    public function getTokenParsers()
    {
        return [new Project_Set_TokenParser()];
    }

    // ...
}

In the above code, we have added a single new tag, defined by the Project_Set_TokenParser class. The Project_Set_TokenParser 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 Project_Twig_Extension 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 Project_Twig_Extension 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;
  関数/静的メソッド: 実装が簡単で高速です (すべての Twigcore 拡張機能で使用されます)。しかし、ランタイムが外部オブジェクトに依存するのは困難です。
• 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 Project_Twig_Extension 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 ('Project_Twig_RuntimeExtension' === $class) {
            return new $class(new Rot13Provider());
        } else {
            // ...
        }
    }
}

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

It is now possible to move the runtime logic to a new Project_Twig_RuntimeExtension 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 Project_Twig_RuntimeExtension
{
    private $rot13Provider;

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

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

class Project_Twig_Extension extends \Twig\Extension\AbstractExtension
{
    public function getFunctions()
    {
        return [
            new \Twig\TwigFunction('rot13', ['Project_Twig_RuntimeExtension', 'rot13']),
            // or
            new \Twig\TwigFunction('rot13', 'Project_Twig_RuntimeExtension::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/
        foo.test
        bar.test
    functions/
        foo.test
        bar.test
    tags/
        foo.test
        bar.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

use Twig\Test\IntegrationTestCase;

class Project_Tests_IntegrationTest extends IntegrationTestCase
{
    public function getExtensions()
    {
        return [
            new Project_Twig_Extension1(),
            new Project_Twig_Extension2(),
        ];
    }

    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.