Twig Filters | Learn Drupal

Last revision: 2024-11-07

Overview

Twig filters let you modify a variable's data before you print them or use it in Twig code blocks. Filters are separated from the variable or expression by a pipe symbol (also known as vertical bar).

Example:

{{ var | some_filter }}

→ the value of var_name is passed to the filter_name filter, which acts like a function and returns the modified value. That modified value is then printed.

Twig itself provides a number of built-in filters. Applications that use Twig, like Drupal and most other Symfony apps, often add additional filters, and you can add your own through your own custom code.

In the following example Twig takes the value of the email variable, runs it through the lower filter, and then prints the result via the {{ }} tags:

<p>
 Your email address: {{ email | lower }}
</p>

Note that the email variable itself is not affected by the filter action. Filters don't modify the variables they act on; they take a copy of the variable's value(s), perform the filter action, and return the modified value.

Activity 1

Use Twig Playground to set up the following scenario:

PHP Variables

$email = "HELLO@example.com";

Twig Template

<p>original value: {{ email }}</p>
<p>filtered value: {{ email | lower }}</p>
<p>value after filtering: {{ email }}</p>

Inspect the output. Does it conform or contradict that the email variable itself is not modified by the filter action, only a copy of the value of the variable?

Answer / solution

The example confirms the statement.

The output is:

<p>original value: HELLO@example.com</p>
<p>filtered value: hello@example.com</p>
<p>value after filtering: HELLO@example.com</p>

By printing {{ email }} again after the filtering action, we see that it has kept its original value.

Filters with arguments

Just like functions, filters can accept one or more arguments.

The following example shows the pub_datetime variable being printed twice:

<h1>Recipe: How to cook rice</h1>
<div>
 <time datetime="{{ pub_datetime }}">{{ pub_datetime | date('Y/m/d') }}</time>
</div>

In the above example:

First we print the datetime in its original format: {{ pub_datetime }}.
Then we print the datetime in a custom format: {{ pub_datetime | date('Y/m/d') }}.
After applying the date filter, the variable pub_datetime has retained its original value.

Output:

<h1>Recipe: How to cook rice</h1>
<div>
 <time datetime="2020-11-03T17:34:01">2020/11/03</time>
</div>

Chaining filters

If you want to use multiple filters on the same variable, you can chain the filters together. The output from the first filter is then taken as the input for the second filter, and so on.

Example

PHP Variables

$my_friends = [ 'Mei', 'Yan', 'Hao' ];

Twig template

My friends are: {{ my_friends | sort | join(', ') }}

Output

My friends are: Hao, Mei, Yan.

Explanation

The values in the my_friends sequence are sent to the sort filter to sort them alphabetically. The resulting sequence is sent to the join filter which joins them together as a string, with each item separated by the provided character(s) (', ').

Again, after these two filters are applied the resulting string is printed, and my_friends still contains the original, unordered sequence.

More filters

Twig has a number of useful built-in filters such as:

upper and lower
date and datetime
split and join

→ refer to the Twig documentation for a full list of built-in Twig filters.

Activity 2

Use the Twig documentation to look up the previously mentioned filters:

upper
lower
date
datetime
split
join

What do they do, and which arguments do they take, if any?

Summary

Twig filters modify data before use.
Twig filters return modified data; they do not modify the original variable itself.
Use {{ my_var | some_filter }} to run the my_var variable through the some_filter filter before being printed or used in calculations.
Twig filters can accept one or more arguments, and behave just like functions.
Twig comes with a number of built-in filters and supports custom filters.