Filters

url_encode

The url_encode filter percent encodes a given string as URL segment or an array as query string:

{{ "path-seg*ment"|url_encode }}
{# outputs "path-seg%2Ament" #}

{{ "string with spaces"|url_encode }}
{# outputs "string%20with%20spaces" #}

{{ {'param': 'value', 'foo': 'bar'}|url_encode }}
{# outputs "param=value&foo=bar" #}

upper

The upper filter converts a value to uppercase:

{{ 'welcome'|upper }}

{# outputs 'WELCOME' #}

trim

The trim filter strips whitespace (or other characters) from the beginning and end of a string:

{{ '  I like Twig.  '|trim }}

{# outputs 'I like Twig.' #}

{{ '  I like Twig.'|trim('.') }}

{# outputs '  I like Twig' #}

Arguments

• character_mask: The characters to strip

title

The title filter returns a titlecased version of the value. Words will start with uppercase letters, all remaining characters are lowercase:

{{ 'my first car'|title }}

{# outputs 'My First Car' #}

striptags

The striptags filter strips SGML/XML tags and replace adjacent whitespace by one space:

{{ some_html|striptags }}

split

The split filter splits a string by the given delimiter and returns a list of strings:

{% set foo = "one,two,three"|split(',') %}
{# foo contains ['one', 'two', 'three'] #}

You can also pass a limit argument:

• If limit is positive, the returned array will contain a maximum of limit elements with the last element containing the rest of string;
• If limit is negative, all components except the last -limit are returned;
• If limit is zero, then this is treated as 1.

{% set foo = "one,two,three,four,five"|split(',', 3) %}
{# foo contains ['one', 'two', 'three,four,five'] #}

If the delimiter is an empty string, then value will be split by equal chunks. Length is set by the limit argument (one character by default).

{% set foo = "123"|split('') %}
{# foo contains ['1', '2', '3'] #}

{% set bar = "aabbcc"|split('', 2) %}
{# bar contains ['aa', 'bb', 'cc'] #}

Arguments

• delimiter: The delimiter
• limit: The limit argument

sort

The sort filter sorts an array:

{% for user in users|sort %}
    ...
{% endfor %}

Slice

The slice filter extracts a slice of a sequence, a mapping, or a string:

{% for i in [1, 2, 3, 4, 5]|slice(1, 2) %}
    {# will iterate over 2 and 3 #}
{% endfor %}

{{ '12345'|slice(1, 2) }}

{# outputs 23 #}

You can use any valid expression for both the start and the length:

{% for i in [1, 2, 3, 4, 5]|slice(start, length) %}
    {# ... #}
{% endfor %}

As syntactic sugar, you can also use the [] notation:

{% for i in [1, 2, 3, 4, 5][start:length] %}
    {# ... #}
{% endfor %}

{{ '12345'[1:2] }} {# will display "23" #}

{# you can omit the first argument -- which is the same as 0 #}
{{ '12345'[:2] }} {# will display "12" #}

{# you can omit the last argument -- which will select everything till the end #}
{{ '12345'[2:] }} {# will display "345" #}

The slice filter works as the array_slice PHP function for arrays and mb_substr for strings with a fallback to substr.

If the start is non-negative, the sequence will start at that start in the variable. If start is negative, the sequence will start that far from the end of the variable.

If length is given and is positive, then the sequence will have up to that many elements in it. If the variable is shorter than the length, then only the available variable elements will be present. If length is given and is negative then the sequence will stop that many elements from the end of the variable. If it is omitted, then the sequence will have everything from offset up until the end of the variable.

Arguments

• start: The start of the slice
• length: The size of the slice
• preserve_keys: Whether to preserve key or not (when the input is an array)

round

The round filter rounds a number to a given precision:

{{ 42.55|round }}
{# outputs 43 #}

{{ 42.55|round(1, 'floor') }}
{# outputs 42.5 #}

The round filter takes two optional arguments; the first one specifies the precision (default is 0) and the second the rounding method (default is common):

• common rounds either up or down (rounds the value up to precision decimal places away from zero, when it is half way there -- making 1.5 into 2 and -1.5 into -2);
• ceil always rounds up;
• floor always rounds down.

Arguments

• precision: The rounding precision
• method: The rounding method

reverse

The reverse filter reverses a sequence, a mapping, or a string:

{% for user in users|reverse %}
    ...
{% endfor %}

{{ '1234'|reverse }}

{# outputs 4321 #}

For sequences and mappings, numeric keys are not preserved. To reverse them as well, pass true as an argument to thereverse filter:

{% for key, value in {1: "a", 2: "b", 3: "c"}|reverse %}
    {{ key }}: {{ value }}
{%- endfor %}

{# output: 0: c    1: b    2: a #}

{% for key, value in {1: "a", 2: "b", 3: "c"}|reverse(true) %}
    {{ key }}: {{ value }}
{%- endfor %}

{# output: 3: c    2: b    1: a #}

Arguments

• preserve_keys: Preserve keys when reversing a mapping or a sequence.

replace

The replace filter formats a given string by replacing the placeholders (placeholders are free-form):

{{ "I like %this% and %that%."|replace({'%this%': foo, '%that%': "bar"}) }}

{# outputs I like foo and bar
   if the foo parameter equals to the foo string. #}

Arguments

• replace_pairs: The placeholder values

raw

The raw filter marks the value as being "safe", which means that in an environment with automatic escaping enabled this variable will not be escaped if raw is the last filter applied to it:

{% autoescape %}
    {{ var|raw }} {# var won't be escaped #}
{% endautoescape %}

number_format

The number_format filter formats numbers. It is a wrapper around PHP's number_format function:

{{ 200.35|number_format }}

You can control the number of decimal places, decimal point, and thousands separator using the additional arguments:

{{ 9800.333|number_format(2, '.', ',') }}

If no formatting options are provided then Twig will use the default formatting options of:

• 0 decimal places.
• . as the decimal point.
• , as the thousands separator.

Arguments

• decimal: The number of decimal points to display
• decimal_point: The character(s) to use for the decimal point
• thousand_sep: The character(s) to use for the thousands separator

nl2br

The nl2br filter inserts HTML line breaks before all newlines in a string:

{{ "I like shopping.\nYou will like it too."|nl2br }}
{# outputs

    I like shopping.<br />
    You will like it too.

#}

The nl2br filter pre-escapes the input before applying the transformation.

merge

The merge filter merges an array with another array:

{% set values = [1, 2] %}

{% set values = values|merge(['apple', 'orange']) %}

{# values now contains [1, 2, 'apple', 'orange'] #}

New values are added at the end of the existing ones.

The merge filter also works on hashes:

{% set items = { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'unknown' } %}

{% set items = items|merge({ 'peugeot': 'car', 'renault': 'car' }) %}

{# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car', 'renault': 'car' } #}

For hashes, the merging process occurs on the keys: if the key does not already exist, it is added but if the key already exists, its value is overridden.

lower

The lower filter converts a value to lowercase:

{{ 'WELCOME'|lower }}

{# outputs 'welcome' #}

length

The length filter returns the number of items of a sequence or mapping, or the length of a string:

{% if users|length > 10 %}
    ...
{% endif %}

last

The last filter returns the last "element" of a sequence, a mapping, or a string:

{{ [1, 2, 3, 4]|last }}
{# outputs 4 #}

{{ { a: 1, b: 2, c: 3, d: 4 }|last }}
{# outputs 4 #}

{{ '1234'|last }}
{# outputs 4 #}

keys

The keys filter returns the keys of an array. It is useful when you want to iterate over the keys of an array:

{% for key in array|keys %}
    ...
{% endfor %}

json_encode

The json_encode filter returns the JSON representation of a value:

{{ data|json_encode() }}

Arguments

• options: A bitmask of json_encode options ({{ data|json_encode(constant('JSON_PRETTY_PRINT')) }})

join

The join filter returns a string which is the concatenation of the items of a sequence:

{{ [1, 2, 3]|join }}
{# returns 123 #}

The separator between elements is an empty string per default, but you can define it with the optional first parameter:

{{ [1, 2, 3]|join('|') }}
{# outputs 1|2|3 #}

Arguments

• glue: The separator

format

The format filter formats a given string by replacing the placeholders (placeholders follows the sprintf notation):

{{ "I like %s and %s."|format(foo, "bar") }}

{# outputs I like foo and bar
   if the foo parameter equals to the foo string. #}

first

The first filter returns the first "element" of a sequence, a mapping, or a string:

{{ [1, 2, 3, 4]|first }}
{# outputs 1 #}

{{ { a: 1, b: 2, c: 3, d: 4 }|first }}
{# outputs 1 #}

{{ '1234'|first }}
{# outputs 1 #}

escape

The escape filter escapes a string for safe insertion into the final output. It supports different escaping strategies depending on the template context.

By default, it uses the HTML escaping strategy:

{{ product.title|escape }}

For convenience, the e filter is defined as an alias:

{{ product.title|e }}

The escape filter can also be used in other contexts than HTML thanks to an optional argument which defines the escaping strategy to use:

{{ product.title|e }}
{# is equivalent to #}
{{ product.title|e('html') }}

And here is how to escape variables included in JavaScript code:

{{ product.title|escape('js') }}
{{ product.title|e('js') }}

The escape filter supports the following escaping strategies:

• html: escapes a string for the HTML body context.
• js: escapes a string for the JavaScript context.
• css: escapes a string for the CSS context. CSS escaping can be applied to any string being inserted into CSS and escapes everything except alphanumerics.
• url: escapes a string for the URI or parameter contexts. This should not be used to escape an entire URI; only a subcomponent being inserted.
• html_attr: escapes a string for the HTML attribute context.

Arguments

• strategy: The escaping strategy
• charset: The string charset

default

The default filter returns the passed default value if the value is undefined or empty, otherwise the value of the variable:

{{ var|default('var is not defined') }}

{{ var.foo|default('foo item on var is not defined') }}

{{ var['foo']|default('foo item on var is not defined') }}

{{ ''|default('passed var is empty')  }}

When using the default filter on an expression that uses variables in some method calls, be sure to use the default filter whenever a variable can be undefined:

{{ var.method(foo|default('foo'))|default('foo') }}

Arguments

• default: The default value

date_modify

The date_modify filter modifies a date with a given modifier string:

{{ product.created_at|date_modify("+1 day")|date("m/d/Y") }}

The date_modify filter accepts strings (it must be in a format supported by the strtotime function) or DateTime instances. You can easily combine it with the date filter for formatting.

Arguments

• modifier: The modifier

date

The date filter formats a date to a given format:

{{ product.created_at|date("m/d/Y") }}

The format specifier is the same as supported by date, except when the filtered data is of type DateInterval, when the format must conform to DateInterval::format instead.

The date filter accepts strings (it must be in a format supported by the strtotimefunction), DateTime instances, or DateInterval instances.

For instance, to display the current date, filter the word "now":

{{ "now"|date("m/d/Y") }}

To escape words and characters in the date format use \\ in front of each character:

{{ product.created_at|date("F jS \\a\\t g:ia") }}

If the value passed to the date filter is null, it will return the current date by default. If an empty string is desired instead of the current date, use a ternary operator:

{{ product.created_at is empty ? "" : product.created_at|date("m/d/Y") }}

Timezone can be passed like this:

{{ product.created_at|date("m/d/Y", "Europe/Paris") }}

Arguments

• format: The date format
• timezone: The date timezone

capitalize

The capitalize filter capitalizes a value. The first character will be uppercase, all others lowercase:

{{ 'my first car'|capitalize }}

{# outputs 'My first car' #}

batch

New in version 1.12.3: The batch filter was added in Twig 1.12.3.

The batch filter "batches" items by returning a list of lists with the given number of items. A second parameter can be provided and used to fill in missing items:

{% set items = ['a', 'b', 'c', 'd', 'e', 'f', 'g'] %}

<table>
{% for row in items|batch(3, 'No item') %}
    <tr>
        {% for column in row %}
            <td>{{ column }}</td>
        {% endfor %}
    </tr>
{% endfor %}
</table>

The above example will be rendered as:

<table>
    <tr>
        <td>a</td>
        <td>b</td>
        <td>c</td>
    </tr>
    <tr>
        <td>d</td>
        <td>e</td>
        <td>f</td>
    </tr>
    <tr>
        <td>g</td>
        <td>No item</td>
        <td>No item</td>
    </tr>
</table>

Arguments

• size: The size of the batch; fractional numbers will be rounded up
• fill: Used to fill in missing items

abs

The abs filter returns the absolute value.

{# number = -5 #}

{{ number|abs }}

{# outputs 5 #}