Default Filters

Usage:

Filters must be embedded in double curly brackets {{ … }}. The filter must be appended after the content / placeholder to apply to with a pipe (|).

Example:

{{ "[post_title]"|trim|upper }}

This example uses two filters. The first trims the post title and the second transforms it to upper case.

Note

You can combine multiple filters.

Note

You can use all default Twig filters.

batch

The batch filter is very useful if you are working with a HTML template and want to show list data in a table. The batch filter divides the list in smaller parts of lists. The size of the lists is defined by the first parameter. The second parameter can be used to fill missing items.

Let’s assume [post_tags_array] contains this list data: Array(“Butter”, “Milk”, “Sugar”, “Eggs”, “Salt”, “Oil”, “Vanilla”)

<table>
{% for row in [post_tags_array]|batch(3, 'No tag') %}
    <tr>
        {% for column in row %}
            <td>{{ column }}</td>
        {% endfor %}
    </tr>
{% endfor %}
</table>

The example will be rendered as:

<table>
    <tr>
        <td>Butter</td>
        <td>Milk</td>
        <td>Sugar</td>
    </tr>
    <tr>
        <td>Eggs</td>
        <td>Salt</td>
        <td>Oil</td>
    </tr>
    <tr>
        <td>Vanilla</td>
        <td>No tag</td>
        <td>No tag</td>
    </tr>
</table>

capitalize

The capitalize filter capitalizes a placeholder string. The first value will be uppercase, the others lowercase.

{{ "[post_title]"|capitalize }}

convert_encoding

If you are sending HTML mails, the convert_encoding filter can be useful if you have issues with character encodings. This filter converts a string from one encoding to another. The first argument is the expected output charset, the second argument is the input charset.

{{ "[post_title]"|convert_encoding('UTF-8', 'iso-2022-jp') }}

Note

This filter relies on the iconv or mbstring extension, so one of them must be installed.

date

Formats the post date to a given format:

{{ "[post_date]"|date("m/d/Y") }}

The format specifier is the same as supported by the PHP function date.

date_modify

With the date_modify filter you can modify dates with a given modifier string. It accepts strings (it must be in a format supported by the strtotime function) or DateTime instances. You can combine it with the date filter.

{{ "[post_date]2|date_modify("+1 day")|date("m/d/Y") }}

default

The default filter returns the passed default value if the placeholder value is undefined or empty.

{{ "[post_excerpt]"|default('excerpt is not defined') }}

escape

The escape filter can be used to escape a placeholder’s value for safe insertion into the message. By default, it uses the HTML escaping strategy. An optional argument defines the escaping strategy to use.

{{ "[author_display_name]"|escape }}
{{ "[author_display_name]"|escape('js') }}
{{ "[author_display_name]"|escape('css') }}
{{ "[author_display_name]"|escape('url') }}
{{ "[author_display_name]"|escape('html_attr') }}

first

The first filter returns the first “element” of a sequence, a mapping, or a string.

Let’s assume [post_tags_array] contains this list data: Array(“Butter”, “Milk”, “Sugar”)

{{ [post_tags_array]|first }}

This example will retrieve “Butter”.

format

The format filter formats a given string by replacing the placeholders which follow the sprintf notation.

{{ "I like %s and %s."|format("WordPress", "Post Status Notifier") }}

join

The join filter returns a string which is the concatenation of the items of a list. You can define the separator between the elements which is an empty string by default.

Let’s assume [post_tags_array] contains this list data: Array(“Butter”, “Milk”, “Sugar”)

{{ [post_tags_array]|join('::') }}

This example results in: Butter::Milk::Sugar

json_encode

The json_encode filter uses the PHP function json_encode and returns the JSON represantation of a string.

{{ "[post_tags]"|json_encode() }}

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 [post_tags_array]|keys %}
...
{% endfor %}

last

The last filter returns the last element of a list.

Let’s assume [post_tags_array] contains this list data: Array(“Butter”, “Milk”, “Sugar”)

{{ [post_tags_array]|last }}

This example will retrieve “Sugar”.

length

The length filter returns the length of a list.

Let’s assume [post_tags_array] contains this list data: Array(“Butter”, “Milk”, “Sugar”)

{{ [post_tags_array]|length }}

This example will retrieve “3”.

lower

The lower filter converts a value to lowercase.

{{ "[post_title]"|lower }}

nl2br

The nl2br filter can be useful if you work with HTML templates. It inserts HTML line breaks before newlines in a string.

{{ "[post_content]"|nl2br }}

number_format

The number_format formats numbers. It uses the PHP function number_format. Using additional arguments you can set the number of decimal places, decimal point, and thousands separator.

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

merge

With the merge filter you can merge two arrays.

{{ [post_tags_array]|merge([post_categories_array])) }}

This example joins the post tags and categories into one array.

upper

The upper filter converts a value to uppercase.

{{ "[post_title]"|upper }}

replace

This will replace the strings “iPhone” and “Galaxy S5” in the post title to “Smartphone”:

{{ "[post_title]"|replace({'iPhone': 'Smartphone', 'Galaxy S5': 'Smartphone'}) }}

reverse

The reverse filter reverses a list.

Let’s assume [post_tags] contains this information: Array(“Butter”, “Milk”, “Sugar”)

{{ [post_tags_array]|reverse|join(',') }}

This example will retrieve “Sugar,Milk,Butter”.

round

The round filter rounds a number to a given precision. It takes two optional arguments; the first one specifies the precision (default is 0) and the second the rounding method. Available methods are “floor”, “ceil” and “common” (default is common):

{{ 45.68|round }}
{{ 45.68|round(1, 'floor') }}

slice

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

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

Outputs: 23

sort

The sort filter sorts an array.

Let’s assume [post_tags_array] contains this information: Array(“Sugar”, “Butter”, “Milk”)

{{ [post_tags_array]|sort }}

The result will be: Array(“Butter”, “Milk”, “Sugar”)

split

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

<ul>{% for key in "[post_custom_fields]"|split(',') %}
  <li>{{ key|trim }}</li>
{% endfor %}</ul>

title

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

{{ "[post_title]"|title }}

If [post_title] contains my cool new post, this filter would return My Cool New Post.

trim

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

{{ "[post_title]"|trim }}

If [post_title] contains “   my cool new post   “ this filter would return “my cool new post”.

url_encode

The url_encode filter 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(true) }}
# outputs "string%20with%20spaces"
{{ {'param': 'value', 'foo': 'bar'}|url_encode }}
# outputs "param=value&foo=bar"

Note

Check out the Twig documentation page for more details about filters.