Twig 模板设计师指南

全局变量

以下变量始终在模板中可用

• _self：引用当前模板名称；
• _context：引用当前上下文；
• _charset：引用当前字符集。

设置变量

您可以在代码块内为变量赋值。赋值使用 set 标签

1
2
3

{% set name = 'Fabien' %}
{% set numbers = [1, 2] %}
{% set map = {'city': 'Paris'} %}

手动转义

如果启用了手动转义，则 您 有责任在需要时转义变量。要转义什么？来自不受信任来源的任何变量。

转义通过使用 escape 或 e 过滤器来完成

1

{{ user.username|e }}

默认情况下，escape 过滤器使用 html 策略，但根据转义上下文，您可能需要显式使用另一种策略

1
2
3
4

{{ user.username|e('js') }}
{{ user.username|e('css') }}
{{ user.username|e('url') }}
{{ user.username|e('html_attr') }}

自动转义

无论是否启用自动转义，您都可以使用 autoescape 标签标记要转义或不转义的模板部分

1
2
3

{% autoescape %}
    Everything will be automatically escaped in this block (using the HTML strategy)
{% endautoescape %}

默认情况下，自动转义使用 html 转义策略。如果您在其他上下文中输出变量，则需要使用适当的转义策略显式转义它们

1
2
3

{% autoescape 'js' %}
    Everything will be automatically escaped in this block (using the JS strategy)
{% endautoescape %}

字面量

表达式最简单的形式是字面量。字面量是 PHP 类型（如字符串、数字和数组）的表示形式。存在以下字面量

• "Hello World"：两个双引号或单引号之间的所有内容都是字符串。当您需要在模板中使用字符串时，它们很有用（例如，作为函数调用、过滤器的参数，或者只是扩展或包含模板）。

  请注意，某些字符需要转义

  • \f：换页符
  • \n：换行符
  • \r：回车符
  • \t：水平制表符
  • \v：垂直制表符
  • \x：十六进制转义序列
  • \0 到 \377：表示字符的八进制转义序列
  • \：反斜杠

  使用单引号字符串时，单引号字符 (') 需要用反斜杠 (\') 转义。使用双引号字符串时，双引号字符 (") 需要用反斜杠 (\") 转义。

  例如，如果单引号字符串前面有反斜杠 (\)，则可以包含分隔符，例如 'It\'s good'。如果字符串包含反斜杠（例如 'c:\Program Files'），请通过将其加倍来转义它（例如 'c:\\Program Files'）。

• 42 / 42.23：整数和浮点数通过写下数字来创建。如果存在点，则该数字为浮点数，否则为整数。下划线可以用作数字分隔符以
  提高可读性（-3_141.592_65 等同于 -3141.59265）。
• ["first_name", "last_name"]：序列由逗号 (,) 分隔并用方括号 ([]) 包裹的表达式序列定义。

• {"name": "Fabien"}：映射由逗号 (,) 分隔并用花括号 ({}) 包裹的键和值列表定义

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

  {# keys as string #}
  {'name': 'Fabien', 'city': 'Paris'}
  
  {# keys as names (equivalent to the previous mapping) #}
  {name: 'Fabien', city: 'Paris'}
  
  {# keys as integer #}
  {2: 'Twig', 4: 'Symfony'}
  
  {# keys can be omitted if it is the same as the variable name #}
  {Paris}
  {# is equivalent to the following #}
  {'Paris': Paris}
  
  {# keys as expressions (the expression must be enclosed into parentheses) #}
  {% set key = 'name' %}
  {(key): 'Fabien', (1 + 1): 2, ('ci' ~ 'ty'): 'city'}

• true / false：true 表示真值，false 表示假值。
• null：null 表示没有特定值。这是变量不存在时返回的值。none 是 null 的别名。

序列和映射可以嵌套

1

{% set complex = [1, {"name": "Fabien"}] %}

字符串插值

字符串插值 (#{expression}) 允许任何有效表达式出现在 双引号字符串 中。评估该表达式的结果将插入到字符串中

1
2

{{ "first #{middle} last" }}
{{ "first #{1 + 2} last" }}

1
2

{# outputs first #{1 + 2} last #}
{{ "first \#{1 + 2} last" }}

数学运算

Twig 允许您在模板中进行数学运算；支持以下运算符

• +：将两个数字相加（操作数转换为数字）。{{ 1 + 1 }} 为 2。
• -：从第一个数字中减去第二个数字。{{ 3 - 2 }} 为 1。
• /：将两个数字相除。返回的值将是浮点数。{{ 1 / 2 }} 为 {{ 0.5 }}。
• %：计算整数除法的余数。{{ 11 % 7 }} 为 4。
• //：将两个数字相除并返回向下取整的整数结果。{{ 20 // 7 }} 为 2，{{ -20 // 7 }} 为 -3（这只是 round 过滤器的语法糖）。
• *：将左操作数与右操作数相乘。{{ 2 * 2 }} 将返回 4。
• **：将左操作数提升为右操作数的幂。{{ 2 ** 3 }} 将返回 8。请注意，** 运算符是右结合的，这意味着 {{ -1**0 }} 等同于 {{ -(1**0) }} 而不是 {{ (-1)**0 }}。

逻辑运算

您可以使用以下运算符组合多个表达式

• and：如果左操作数和右操作数均为真，则返回 true。
• xor：如果左操作数或右操作数 之一 为真，但不能两者都为真，则返回 true。
• or：如果左操作数或右操作数为真，则返回 true。
• not：否定语句。
• (expr)：对表达式进行分组。

比较运算

任何表达式中都支持以下数学比较运算符：==、!=、<、>、>= 和 <=。

飞船运算符

飞船运算符 (<=>) 用于比较两个表达式。当第一个操作数分别小于、等于或大于第二个操作数时，它返回 -1、0 或 1。

可迭代运算符

检查可迭代对象 has every 或 has some 的元素是否返回 true，使用箭头函数。箭头函数接收可迭代对象的值作为其参数

1
2
3
4
5
6
7

{% set sizes = [34, 36, 38, 40, 42] %}

{% set hasOnlyOver38 = sizes has every v => v > 38 %}
{# hasOnlyOver38 is false #}

{% set hasOver38 = sizes has some v => v > 38 %}
{# hasOver38 is true #}

对于空的可迭代对象，has every 返回 true，而 has some 返回 false。

包含运算符

in 运算符执行包含测试。如果左操作数包含在右操作数中，则返回 true

1
2
3
4
5

{# returns true #}

{{ 1 in [1, 2, 3] }}

{{ 'cd' in 'abcde' }}

要执行否定测试，请使用 not in 运算符

1
2
3
4

{% if 1 not in [1, 2, 3] %}

{# is equivalent to #}
{% if not (1 in [1, 2, 3]) %}

starts with 和 ends with 运算符用于检查字符串是否以给定的子字符串开头或结尾

1
2
3
4
5

{% if 'Fabien' starts with 'F' %}
{% endif %}

{% if 'Fabien' ends with 'n' %}
{% endif %}

1
2

{% if phone matches '/^[\\d\\.]+$/' %}
{% endif %}

测试运算符

is 运算符执行测试。测试可用于针对常见表达式测试变量。右操作数是测试的名称

1
2
3

{# find out if a variable is odd #}

{{ name is odd }}

测试也可以接受参数

1

{% if post.status is constant('Post::PUBLISHED') %}

可以通过使用 is not 运算符来否定测试

1
2
3
4

{% if post.status is not constant('Post::PUBLISHED') %}

{# is equivalent to #}
{% if not (post.status is constant('Post::PUBLISHED')) %}

转到 测试 页面以了解有关内置测试的更多信息。

其他运算符

以下运算符不属于任何其他类别

• |：应用过滤器。

• ..：基于运算符之前和之后的运算数创建序列（这是 range 函数的语法糖）

  1
  2
  3
  4

  {% for i in 1..5 %}{{ i }}{% endfor %}
  
  {# is equivalent to #}
  {% for i in range(1, 5) %}{{ i }}{% endfor %}

  请注意，由于 运算符优先级规则，当将其与过滤器运算符组合时，必须使用括号

  1

  {{ (1..5)|join(', ') }}

• ~：将所有操作数转换为字符串并将它们连接起来。{{ "Hello " ~ name ~ "!" }} 将返回（假设 name 是 'John'）Hello John!。

• ., []：获取变量的属性。

  (.) 运算符抽象了获取变量的属性（PHP 对象的方法、属性或常量，或 PHP 数组的项）

  1
  2
  3
  4

  {{ user.name }}
  
  Twig supports a specific syntax via the ``[]`` operator for accessing items
  on sequences and mappings, like in ``user['name']``:

  在 . 之后，您可以通过用括号 () 将其包装起来来使用任何表达式。

  一种用例是当属性包含特殊字符时（例如 -，它将被解释为减号运算符）

  1
  2

  {# equivalent to the non-working user.first-name #}
  {{ user.('first-name') }}

  另一种用例是当属性是“动态的”（通过变量定义）时

  1
  2

  {{ user.(name) }}
  {{ user.('get' ~ name) }}

  在 Twig 3.15 之前，对于之前的两个用例，请改用 attribute 函数。

  Twig 通过 [] 运算符支持特定语法，用于访问序列和映射上的项

  1

  {{ user['name'] }}

  调用方法时，可以使用 () 运算符传递参数

  1
  2
  3
  4

  {{ html.generate_input() }}
  {{ html.generate_input('pwd', 'password') }}
  {# or using named arguments #}
  {{ html.generate_input(name: 'pwd', type: 'password') }}

  PHP 实现

  为了将 user.name 解析为 PHP 调用，Twig 在运行时使用以下算法

  • 检查 user 是否是 PHP 数组或 ArrayObject/ArrayAccess 对象，以及 name 是否是有效元素；
  • 如果不是，并且如果 user 是 PHP 对象，请检查 name 是否是有效属性；
  • 如果不是，并且如果 user 是 PHP 对象，请检查 name 是否是类常量；
  • 如果不是，并且如果 user 是 PHP 对象，请检查以下方法并调用第一个有效方法：name()、getName()、isName() 或 hasName()；
  • 如果不是，并且如果 strict_variables 为 false，则返回 null；
  • 如果不是，则抛出异常。

  为了将 user['name'] 解析为 PHP 调用，Twig 在运行时使用以下算法

  • 检查 user 是否是数组，以及 name 是否是有效元素；
  • 如果不是，并且如果 strict_variables 为 false，则返回 null；
  • 如果不是，则抛出异常。

  Twig 通过 () 运算符支持特定语法，用于调用对象上的方法，例如 user.name()

  • 检查 user 是否是对象，并且是否具有 name()、getName()、isName() 或 hasName() 方法；
  • 如果不是，并且如果 strict_variables 为 false，则返回 null；
  • 如果不是，则抛出异常。

• ?:：三元运算符

  1
  2
  3

  {{ result ? 'yes' : 'no' }}
  {{ result ?: 'no' }} is the same as {{ result ? result : 'no' }}
  {{ result ? 'yes' }} is the same as {{ result ? 'yes' : '' }}

• ??：null 合并运算符

  1
  2

  {# returns the value of result if it is defined and not null, 'no' otherwise #}
  {{ result ?? 'no' }}

• ...：展开运算符可用于展开序列或映射，或展开函数调用的参数

  1
  2
  3
  4

  {% set numbers = [1, 2, ...moreNumbers] %}
  {% set ratings = {'q1': 10, 'q2': 5, ...moreRatings} %}
  
  {{ 'Hello %s %s!'|format(...['Fabien', 'Potencier']) }}

  3.15

  对展开函数调用的参数的支持是在 Twig 3.15 中引入的。

• =>：箭头运算符允许创建函数。函数由参数（使用括号表示多个参数）和一个箭头 (=>) 后跟要执行的表达式组成。表达式可以访问所有传递的参数。箭头函数作为过滤器、函数、测试、宏和方法调用的参数受支持。

  例如，内置的 map、reduce、sort、filter 和 find 过滤器接受箭头函数作为参数

  1

  {{ people|map(p => p.first_name)|join(', ') }}

  箭头函数可以存储在变量中

  1
  2
  3

  {% set first_name_fn = (p) => p.first_name %}
  
  {{ people|map(first_name_fn)|join(', ') }}

  3.15

  Twig 3.15 中添加了对函数、宏和方法调用的箭头函数支持（过滤器和测试已经受支持）。

  可以使用 invoke 过滤器调用箭头函数。

  3.19

  invoke 过滤器已在 Twig 3.19 中添加。

运算符

Twig 使用运算符在模板中执行各种操作。理解这些运算符的优先级对于编写正确且高效的 Twig 模板至关重要。

运算符优先级规则如下，优先级最低的运算符首先列出。

当优先级在 4.0 中更改时，新优先级由箭头 => 指示。

这是 Twig 4.0 的相同表格，其中调整了优先级

在不使用任何括号的情况下，运算符优先级规则用于确定如何将代码转换为 PHP

1
2
3

{{ 6 b-and 2 or 6 b-and 16 }}

{# it is converted to the following PHP code: (6 & 2) || (6 & 16) #}

通过使用括号显式分组表达式来更改默认优先级

1
2
3
4
5
6
7

{% set greeting = 'Hello ' %}
{% set name = 'Fabien' %}

{{ greeting ~ name|lower }}   {# Hello fabien #}

{# use parenthesis to change precedence #}
{{ (greeting ~ name)|lower }} {# hello fabien #}