Twig for Template Designers

Global Variables

The following variables are always available in templates:

• _self: references the current template name;
• _context: references the current context;
• _charset: references the current charset.

Setting Variables

You can assign values to variables inside code blocks. Assignments use the set tag:

1
2
3

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

Working with Manual Escaping

If manual escaping is enabled, it is your responsibility to escape variables if needed. What to escape? Any variable that comes from an untrusted source.

Escaping works by using the escape or e filter:

1

{{ user.username|e }}

By default, the escape filter uses the html strategy, but depending on the escaping context, you might want to explicitly use another strategy:

1
2
3
4

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

Working with Automatic Escaping

Whether automatic escaping is enabled or not, you can mark a section of a template to be escaped or not by using the autoescape tag:

1
2
3

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

By default, auto-escaping uses the html escaping strategy. If you output variables in other contexts, you need to explicitly escape them with the appropriate escaping strategy:

1
2
3

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

Literals

The simplest form of expressions are literals. Literals are representations for PHP types such as strings, numbers, and arrays. The following literals exist:

• "Hello World": Everything between two double or single quotes is a string. They are useful whenever you need a string in the template (for example as arguments to function calls, filters or just to extend or include a template).

  Note that certain characters require escaping:

  • \f: Form feed
  • \n: New line
  • \r: Carriage return
  • \t: Horizontal tab
  • \v: Vertical tab
  • \x: Hexadecimal escape sequence
  • \0 to \377: Octal escape sequences representing characters
  • \: Backslash

  When using single-quoted strings, the single quote character (') needs to be escaped with a backslash (\'). When using double-quoted strings, the double quote character (") needs to be escaped with a backslash (\").

  For example, a single quoted string can contain a delimiter if it is preceded by a backslash (\) -- like in 'It\'s good'. If the string contains a backslash (e.g. 'c:\Program Files') escape it by doubling it (e.g. 'c:\\Program Files').

• 42 / 42.23: Integers and floating point numbers are created by writing the number down. If a dot is present the number is a float, otherwise an integer. Underscores can be used as digits separator to
  improve readability (-3_141.592_65 is equivalent to -3141.59265).
• ["first_name", "last_name"]: Sequences are defined by a sequence of expressions separated by a comma (,) and wrapped with squared brackets ([]).

• {"name": "Fabien"}: Mappings are defined by a list of keys and values separated by a comma (,) and wrapped with curly braces ({}):

  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 represents the true value, false represents the false value.
• null: null represents no specific value. This is the value returned when a variable does not exist. none is an alias for null.

Sequences and mappings can be nested:

1

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

String Interpolation

String interpolation (#{expression}) allows any valid expression to appear within a double-quoted string. The result of evaluating that expression is inserted into the string:

1
2

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

1
2

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

Math

Twig allows you to do math in templates; the following operators are supported:

• +: Adds two numbers together (the operands are casted to numbers). {{ 1 + 1 }} is 2.
• -: Subtracts the second number from the first one. {{ 3 - 2 }} is 1.
• /: Divides two numbers. The returned value will be a floating point number. {{ 1 / 2 }} is {{ 0.5 }}.
• %: Calculates the remainder of an integer division. {{ 11 % 7 }} is 4.
• //: Divides two numbers and returns the floored integer result. {{ 20 // 7 }} is 2, {{ -20 // 7 }} is -3 (this is just syntactic sugar for the round filter).
• *: Multiplies the left operand with the right one. {{ 2 * 2 }} would return 4.
• **: Raises the left operand to the power of the right operand. {{ 2 ** 3 }} would return 8.

Logic

You can combine multiple expressions with the following operators:

• and: Returns true if the left and the right operands are both true.
• xor: Returns true if either the left or the right operand is true, but not both.
• or: Returns true if the left or the right operand is true.
• not: Negates a statement.
• (expr): Groups an expression.

Comparisons

The following mathematical comparison operators are supported in any expression: ==, !=, <, >, >=, and <=.

Spaceship Operator

The spaceship operator (<=>) is used for comparing two expressions. It returns -1, 0 or 1 when the first operand is respectively less than, equal to, or greater than the second operand.

Iterable Operators

Check that an iterable has every or has some of its elements return true using an arrow function. The arrow function receives the value of the iterable as its argument:

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 #}

For an empty iterable, has every returns true and has some returns false.

Containment Operators

The in operator performs containment test. It returns true if the left operand is contained in the right:

1
2
3
4
5

{# returns true #}

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

{{ 'cd' in 'abcde' }}

To perform a negative test, use the not in operator:

1
2
3
4

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

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

The starts with and ends with operators are used to check if a string starts or ends with a given substring:

1
2
3
4
5

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

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

1
2

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

Test Operator

The is operator performs tests. Tests can be used to test a variable against a common expression. The right operand is name of the test:

1
2
3

{# find out if a variable is odd #}

{{ name is odd }}

Tests can accept arguments too:

1

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

Tests can be negated by using the is not operator:

1
2
3
4

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

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

Go to the tests page to learn more about the built-in tests.

Other Operators

The following operators don't fit into any of the other categories:

• |: Applies a filter.

• ..: Creates a sequence based on the operand before and after the operator (this is syntactic sugar for the range function):

  1
  2
  3
  4

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

  Note that you must use parentheses when combining it with the filter operator due to the operator precedence rules:

  1

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

• ~: Converts all operands into strings and concatenates them. {{ "Hello " ~ name ~ "!" }} would return (assuming name is 'John') Hello John!.

• ., []: Gets an attribute of a variable.

  The (.) operator abstracts getting an attribute of a variable (methods, properties or constants of a PHP object, or items of a PHP array):

  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']``:

  After the ., you can use any expression by wrapping it with parenthesis ().

  One use case is when the attribute contains special characters (like - that would be interpreted as the minus operator):

  1
  2

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

  Another use case is when the attribute is "dynamic" (defined via a variable):

  1
  2

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

  Before Twig 3.15, use the attribute function instead for the two previous use cases.

  Twig supports a specific syntax via the [] operator for accessing items on sequences and mappings:

  1

  {{ user['name'] }}

  When calling a method, you can pass arguments using the () operator:

  1
  2
  3
  4

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

  PHP Implementation

  To resolve user.name to a PHP call, Twig uses the following algorithm at runtime:

  • check if user is a PHP array or a ArrayObject/ArrayAccess object and name a valid element;
  • if not, and if user is a PHP object, check that name is a valid property;
  • if not, and if user is a PHP object, check that name is a class constant;
  • if not, and if user is a PHP object, check the following methods and call the first valid one: name(), getName(), isName(), or hasName();
  • if not, and if strict_variables is false, return null;
  • if not, throw an exception.

  To resolve user['name'] to a PHP call, Twig uses the following algorithm at runtime:

  • check if user is an array and name a valid element;
  • if not, and if strict_variables is false, return null;
  • if not, throw an exception.

  Twig supports a specific syntax via the () operator for calling methods on objects, like in user.name():

  • check if user is a object and has the name(), getName(), isName(), or hasName() method;
  • if not, and if strict_variables is false, return null;
  • if not, throw an exception.

• ?:: The ternary operator:

  1
  2
  3

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

• ??: The null-coalescing operator:

  1
  2

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

• ...: The spread operator can be used to expand sequences or mappings or to expand the arguments of a function call:

  1
  2
  3
  4

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

  3.15

  Support for expanding the arguments of a function call was introduced in Twig 3.15.

• =>: The arrow operator allows the creation of functions. A function is made of arguments (use parentheses for multiple arguments) and an arrow (=>) followed by an expression to execute. The expression has access to all passed arguments. Arrow functions are supported as arguments for filters, functions, tests, macros, and method calls.

  For instance, the built-in map, reduce, sort, filter, and find filters accept arrow functions as arguments:

  1

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

  Arrow functions can be stored in variables:

  1
  2
  3

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

  3.15

  Arrow function support for functions, macros, and method calls was added in Twig 3.15 (filters and tests were already supported).

Operators

Twig uses operators to perform various operations within templates. Understanding the precedence of these operators is crucial for writing correct and efficient Twig templates.

The operator precedence rules are as follows, with the lowest-precedence operators listed first:

Without using any parentheses, the operator precedence rules are used to determine how to convert the code to 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) #}

Change the default precedence by explicitly grouping expressions with parentheses:

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 #}