Filters

The following filters are available to Twig templates in Craft:

`abs`

Returns an absolute value.

This works identically to Twig’s core abs filter.

`append`

Appends HTML to the end of another element.

{{ '<div><p>Lorem</p></div>'|append('<p>Ipsum</p>') }}
{# Output: <div><p>Lorem</p><p>Ipsum</p></div> #}

If you only want to append a new element if one of the same type doesn’t already exist, pass 'keep' as a second argument.

{{ '<div><p>Lorem</p></div>'|append('<p>Ipsum</p>', 'keep') }}
{# Output: <div><p>Lorem</p></div> #}

If you want to replace an existing element of the same type, pass 'replace' as a second argument.

{{ '<div><p>Lorem</p></div>'|append('<p>Ipsum</p>', 'replace') }}
{# Output: <div><p>Ipsum</p></div> #}

`ascii`

Converts a string to ASCII characters.

{{ 'über'|ascii }}
{# Output: uber #}

By default, the current site’s language will be used when choosing ASCII character mappings. You can override that by passing in a different locale ID.

{{ 'über'|ascii('de') }}
{# Output: ueber #}

`atom`

Converts a date to an ISO-8601 timestamp (e.g. 2019-01-29T10:00:00-08:00), which should be used for Atom feeds, among other things.

{{ entry.postDate|atom }}

`attr`

Modifies an HTML tag’s attributes, using the same attribute definitions supported by using api:yii\helpers\BaseHtml::renderTagAttributes().

{% set tag = '<div>' %}
{{ tag|attr({
    class: 'foo'
}) }}
{# Output: <div class="foo"> #}

Only the first tag will be modified, and any HTML comments or doctype declarations before it will be ignored.

{% set svg %}
    <?xml version="1.0" encoding="utf-8"?>
    <svg>...</svg>
{% endset %}
{{ svg|attr({
    class: 'icon'
}) }}
{# Output:
   <?xml version="1.0" encoding="utf-8"?>
   <svg class="icon">...</svg> #}

Attributes can be removed by setting them to false.

{% set tag = '<input type="text" disabled>' %}
{{ tag|attr({
    disabled: false
}) }}
{# Output: <input type="text"> #}

class and style attributes will be combined with the element’s existing attributes, if set.

{% set tag = '<div class="foo" style="color: black;">' %}
{{ tag|attr({
    class: 'bar',
    style: {background: 'red'}
}) }}
{# Output: <div class="foo bar" style="color: black; background: red;"> #}

All other attributes will replace the existing attribute values.

{% set tag = '<input type="text">' %}
{{ tag|attr({
    type: 'email'
}) }}
{# Output: <input type="email"> #}

If you want to completely replace a class or style attribute, remove it first, then set the new value:

{% set tag = '<div class="foo">' %}
{{ tag|attr({class: false})|attr({class: 'bar'}) }}
{# Output: <div class="bar"> #}

`batch`

“Batches” items by returning a list of lists with the given number of items

This works identically to Twig’s core batch filter.

`camel`

Returns a string formatted in “camelCase”.

{{ 'foo bar'|camel }}
{# Output: fooBar #}

`capitalize`

Capitalizes a value.

This works identically to Twig’s core capitalize filter.

`column`

Returns the values from a single column in the input array.

{% set entryIds = entries|column('id') %}

This works similarly to Twig’s core column filter, except that ArrayHelper::getColumn() is used rather than PHP’s array_column() function.

`convert_encoding`

Converts a string from one encoding to another.

This works identically to Twig’s core convert_encoding filter.

`currency`

Formats a number with a given currency according to the user’s preferred language.

{{ 1000000|currency('USD') }}
{# Output: $1,000,000.00 #}

You can pass stripZeros=true to remove any fraction digits if the value to be formatted has no minor value (e.g. cents):

{{ 1000000|currency('USD', stripZeros=true) }}
{# Output: $1,000,000 #}

`date`

Formats a timestamp or DateTime object.

{{ entry.postDate|date }}
{# Output: Dec 20, 1990 #}

You can customize how the date is presented by passing a custom date format, just like Twig’s core date filter:

{{ 'now'|date('m/d/Y') }}
{# Output: 12/20/1990 #}

Craft also provides some special format keywords that will output locale-specific date formats:

Format	Example
`short`	12/20/1990
`medium` (default)	Dec 20, 1990
`long`	December 20, 1990
`full`	Thursday, December 20, 1990

{{ entry.postDate|date('short') }}
{# Output: 12/20/1990 #}

The current application locale will be used by default. If you want to format the date for a different locale, use the locale argument:

{{ entry.postDate|date('short', locale='en-GB') }}
{# Output: 20/12/1990 #}

You can customize the timezone the time is output in, using the timezone param:

{{ entry.postDate|date('short', timezone='UTC') }}
{# Output: 12/21/1990 #}

`date_modify`

Modifies a date with a given modifier string.

This works identically to Twig’s core date_modify filter.

`datetime`

Formats a timestamp or DateTime object, including the time of day.

{{ entry.postDate|datetime }}
{# Output: Dec 20, 1990, 5:00:00 PM #}

Craft provides some special format keywords that will output locale-specific date and time formats:

{{ entry.postDate|datetime('short') }}
{# Output: 9/26/2018, 5:00 PM #}

Possible format values are:

Format	Example
`short`	12/20/1990, 5:00 PM
`medium` (default)	Dec 20, 1990, 5:00:00 PM
`long`	December 20, 1990 at 5:00:00 PM PDT
`full`	Thursday, December 20, 19909 at 5:00:00 PM PDT

The current application locale will be used by default. If you want to format the date and time for a different locale, use the locale argument:

{{ entry.postDate|datetime('short', locale='en-GB') }}
{# Output: 20/12/1990, 17:00 #}

You can customize the timezone the time is output in, using the timezone param:

{{ entry.postDate|datetime('short', timezone='UTC') }}
{# Output: 12/21/1990, 12:00 AM #}

`default`

Returns the passed default value if the value is undefined or empty, otherwise the value of the variable.

This works identically to Twig’s core default filter.

`duration`

Runs a DateInterval object through api:craft\helpers\DateTimeHelper::humanDurationFromInterval()

<p>Posted {{ entry.postDate.diff(now)|duration(false) }} ago.</p>

`encenc`

Encrypts and base64-encodes a string.

{{ 'secure-string'|encenc }}

`escape`

Escapes a string using strategies that depend on the context.

This works identically to Twig’s core escape filter.

`filesize`

Formats a number of bytes into something nicer.

`filter`

Filters elements of an array.

If nothing is passed to it, any “empty” elements will be removed.

{% set array = ['foo', '', 'bar', '', 'baz'] %}
{% set filteredArray = array|filter %}
{# Result: ['foo', 'bar', 'baz'] #}

When an arrow function is passed, this works identically to Twig’s core filter filter.

{% set array = ['foo', 'bar', 'baz'] %}
{% set filteredArray = array|filter(v => v[0] == 'b') %}
{# Result: ['bar', 'baz'] #}

`filterByValue`

Runs an array through api:craft\helpers\ArrayHelper::filterByValue().

`first`

Returns the first element of an array or string.

This works identically to Twig’s core first filter.

`format`

formats a given string by replacing the placeholders (placeholders follows the sprintf() notation).

This works identically to Twig’s core format filter.

`group`

Groups the items of an array together based on common properties.

{% set allEntries = craft.entries.section('blog').all() %}
{% set allEntriesByYear = allEntries|group('postDate|date("Y")') %}

{% for year, entriesInYear in allEntriesByYear %}
    <h2>{{ year }}</h2>

    <ul>
        {% for entry in entriesInYear %}
            <li><a href="{{ entry.url }}">{{ entry.title }}</a></li>
        {% endfor %}
    </ul>
{% endfor %}

`hash`

Prefixes the given string with a keyed-hash message authentication code (HMAC), for securely passing data in forms that should not be tampered with.

<input type="hidden" name="foo" value="{{ 'bar'|hash }}">

PHP scripts can validate the value via Security::validateData():

$foo = Craft::$app->request->getBodyParam('foo');
$foo = Craft::$app->security->validateData($foo);

if ($foo !== false) {
    // data is valid
}

`id`

Formats a string into something that will work well as an HTML input id, via api:craft\web\View::formatInputId().

{% set name = 'input[name]' %}
<input type="text" name="{{ name }}" id="{{ name|id }}">

`index`

Runs an array through ArrayHelper::index().

{% set entries = entries|index('id') %}

`indexOf`

Returns the index of a passed-in value within an array, or the position of a passed-in string within another string. (Note that the returned position is 0-indexed.) If no position can be found, -1 is returned instead.

{% set colors = ['red', 'green', 'blue'] %}
<p>Green is located at position {{ colors|indexOf('green') + 1 }}.</p>

{% set position = 'team'|indexOf('i') %}
{% if position != -1 %}
    <p>There <em>is</em> an “i” in “team”! It’s at position {{ position + 1 }}.</p>
{% endif %}

`intersect`

Returns an array containing only the values that are also in a passed-in array.

{% set ownedIngredients = [
    'vodka',
    'gin',
    'triple sec',
    'tonic',
    'grapefruit juice'
] %}

{% set longIslandIcedTeaIngredients = [
    'vodka',
    'tequila',
    'rum',
    'gin',
    'triple sec',
    'sweet and sour mix',
    'Coke'
] %}

{% set ownedLongIslandIcedTeaIngredients =
    ownedIngredients|intersect(longIslandIcedTeaIngredients)
%}

`join`

Returns a string which is the concatenation of the elements in an array.

This works identically to Twig’s core join filter.

`json_encode`

Returns the JSON representation of a value.

This works similarly to Twig’s core json_encode filter, except that the options argument will default to JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_QUOT if the response content type is either text/html or application/xhtml+xml.

`json_decode`

JSON-decodes a string into an array by passing it through api:yii\helpers\Json::decode().

{% set arr = '[1, 2, 3]'|json_decode %}

`kebab`

Returns a string formatted in “kebab-case”.

Tip: That’s a reference to shish kebabs for those of you that don’t get the analogy.

{{ 'foo bar?'|kebab }}
{# Output: foo-bar #}

`keys`

Returns the keys of an array.

This works identically to Twig’s core keys filter.

`last`

Returns the last element of an array or string.

This works identically to Twig’s core last filter.

`lcfirst`

Lowercases the first character of a string.

`length`

Returns the number of elements in an array or string.

This works identically to Twig’s core length filter.

`literal`

Runs a string through api:craft\helpers\Db::escapeParam()

`lower`

Converts a value to lowercase.

This works identically to Twig’s core lower filter.

`map`

Applies an arrow function to the elements of an array.

This works identically to Twig’s core map filter.

`markdown` or `md`

Processes a string with Markdown.

{% set content %}
# Everything You Need to Know About Computer Keyboards

The only *real* computer keyboard ever made was famously
the [Apple Extended Keyboard II] [1].

    [1]: https://www.flickr.com/photos/gruber/sets/72157604797968156/
{% endset %}

{{ content|markdown }}

This filter supports two arguments:

flavor can be 'original' (default value), 'gfm'(GitHub-Flavored Markdown), 'gfm-comment' (GFM with newlines converted to <br>s), or 'extra' (Markdown Extra)
inlineOnly determines whether to only parse inline elements, omitting any <p> tags (defaults to false)

`merge`

Merges an array with another array.

This works identically to Twig’s core merge filter.

`multisort`

Sorts an array with ArrayHelper::multisort().

`nl2br`

Inserts HTML line breaks before all newlines in a string.

This works identically to Twig’s core nl2br filter.

`number`

Formats a number according to the user’s preferred language.

You can optionally pass false to it if you want group symbols to be omitted (e.g. commas in English).

{{ 1000000|number }}
{# Output: 1,000,000 #}

{{ 1000000|number(false) }}
{# Output: 1000000 #}

`number_format`

Formats numbers. It is a wrapper around PHP’s number_format() function:

This works identically to Twig’s core number_format filter.

`parseRefs`

Parses a string for reference tags.

{% set content %}
    {entry:blog/hello-world:link} was my first blog post. Pretty geeky, huh?
{% endset %}

{{ content|parseRefs|raw }}

`pascal`

Returns a string formatted in “PascalCase” (AKA “UpperCamelCase”).

{{ 'foo bar'|pascal }}
{# Output: FooBar #}

`percentage`

Formats a percentage according to the user’s preferred language.

`prepend`

Prepends HTML to the beginning of another element.

{{ '<div><p>Ipsum</p></div>'|prepend('<p>Lorem</p>') }}
{# Output: <div><p>Lorem</p><p>Ipsum</p></div> #}

If you only want to append a new element if one of the same type doesn’t already exist, pass 'keep' as a second argument.

{{ '<div><p>Ipsum</p></div>'|prepend('<p>Lorem</p>', 'keep') }}
{# Output: <div><p>Ipsum</p></div> #}

If you want to replace an existing element of the same type, pass 'replace' as a second argument.

{{ '<div><p>Ipsum</p></div>'|prepend('<p>Lorem</p>', 'replace') }}
{# Output: <div><p>Lorem</p></div> #}

`raw`

Marks a 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.

This works identically to Twig’s core raw filter.

`reduce`

Iteratively reduces a sequence or a mapping to a single value using an arrow function, so as to reduce it to a single value. The arrow function receives the return value of the previous iteration and the current value of the sequence or mapping.

This works identically to Twig’s core reduce filter.

`replace`

Replaces parts of a string with other things.

When a mapping array is passed, this works identically to Twig’s core replace filter:

{% set str = 'Hello, FIRST LAST' %}

{{ str|replace({
    FIRST: currentUser.firstName,
    LAST:  currentUser.lastName
}) }}

Or you can replace one thing at a time:

{% set str = 'Hello, NAME' %}

{{ str|replace('NAME', currentUser.name) }}

You can also use a regular expression to search for matches by starting and ending the replacement string’s value with forward slashes:

{{ tag.title|lower|replace('/[^\\w]+/', '-') }}

`reverse`

Reverses an array or string.

This works identically to Twig’s core reverse filter.

`round`

Rounds a number to a given precision.

This works identically to Twig’s core round filter.

`rss`

Outputs a date in the format required for RSS feeds (D, d M Y H:i:s O).

{{ entry.postDate|rss }}

`slice`

Extracts a slice of an array or string.

This works identically to Twig’s core slice filter.

`snake`

Returns a string formatted in “snake_case”.

{{ 'foo bar'|snake }}
{# Output: foo_bar #}

`sort`

Sorts an array.

This works identically to Twig’s core sort filter.

`spaceless`

Removes whitespace between HTML tags, not whitespace within HTML tags or whitespace in plain text.

This works identically to Twig’s core spaceless filter.

`split`

Splits a string by the given delimiter and returns a list of string.

This works identically to Twig’s core split filter.

`striptags`

Strips SGML/XML tags and replace adjacent whitespace by one space.

This works identically to Twig’s core striptags filter.

`time`

Outputs the time of day for a timestamp or DateTime object.

{{ entry.postDate|time }}
{# Output: 10:00:00 AM #}

Craft provides some special format keywords that will output locale-specific time formats:

{{ entry.postDate|time('short') }}
{# Output: 10:00 AM #}

Possible format values are:

Format	Example
`short`	5:00 PM
`medium` (default)	5:00:00 PM
`long`	5:00:00 PM PDT

The current application locale will be used by default. If you want to format the date and time for a different locale, use the locale argument:

{{ entry.postDate|time('short', locale='en-GB') }}
{# Output: 17:00 #}

You can customize the timezone the time is output in, using the timezone param:

{{ entry.postDate|time('short', timezone='UTC') }}
{# Output: 12:00 AM #}

`timestamp`

Formats a date as a human-readable timestamp, via api:craft\i18n\Formatter::asTimestamp().

`title`

Returns a titlecased version of the value. Words will start with uppercase letters, all remaining characters are lowercase.

This works identically to Twig’s core title filter.

`trim`

Strips whitespace (or other characters) from the beginning and end of a string

This works identically to Twig’s core trim filter.

`translate` or `t`

Translates a message with Craft::t().

{{ 'Hello world'|t('myCategory') }}

If no category is specified, it will default to site.

{{ 'Hello world'|t }}

::: tip See Static Message Translations for a full explanation on how this works. :::

`ucfirst`

Capitalizes the first character of a string.

`ucwords`

Capitalizes the first character of each word in a string.

`unique`

Runs an array through array_unique().

`upper`

Converts a value to uppercase.

This works identically to Twig’s core upper filter.

`url_encode`

Percent-encodes a given string as URL segment or an array as query string.

This works identically to Twig’s core url_encode filter.

`values`

Returns an array of all the values in a given array, but without any custom keys.

{% set arr1 = {foo: 'Foo', bar: 'Bar'} %}
{% set arr2 = arr1|values %}
{# arr2 = ['Foo', 'Bar'] #}

`without`

Returns an array without the specified element(s).

{% set entries = craft.entries.section('articles').limit(3).find %}
{% set firstEntry = entries[0] %}
{% set remainingEntries = entries|without(firstEntry) %}

`withoutKey`

Returns an array without the specified key.

{% set array = {
    foo: 'foo',
    bar: 'bar',
    baz: 'baz'
} %}
{% set filtered = array|withoutKey('baz') %}

Files

filters.md

Latest commit

History

filters.md

File metadata and controls

Filters

abs

append

ascii

atom

attr

batch

camel

capitalize

column

convert_encoding

currency

date

date_modify

datetime

default

duration

encenc

escape

filesize

filter

filterByValue

first

format

group

hash

id

index

indexOf

intersect

join

json_encode

json_decode

kebab

keys

last

lcfirst

length

literal

lower

map

markdown or md

merge

multisort

nl2br

number

number_format

parseRefs

pascal

percentage

prepend

raw

reduce

replace

reverse

round

rss

slice

snake

sort

spaceless

split

striptags

time

timestamp

title

trim

translate or t

ucfirst

ucwords

unique

upper

url_encode

values

`abs`

`append`

`ascii`

`atom`

`attr`

`batch`

`camel`

`capitalize`

`column`

`convert_encoding`

`currency`

`date`

`date_modify`

`datetime`

`default`

`duration`

`encenc`

`escape`

`filesize`

`filter`

`filterByValue`

`first`

`format`

`group`

`hash`

`id`

`index`

`indexOf`

`intersect`

`join`

`json_encode`

`json_decode`

`kebab`

`keys`

`last`

`lcfirst`

`length`

`literal`

`lower`

`map`

`markdown` or `md`

`merge`

`multisort`

`nl2br`

`number`

`number_format`

`parseRefs`

`pascal`

`percentage`

`prepend`

`raw`

`reduce`

`replace`

`reverse`

`round`

`rss`

`slice`

`snake`

`sort`

`spaceless`

`split`

`striptags`

`time`

`timestamp`

`title`

`trim`

`translate` or `t`

`ucfirst`

`ucwords`

`unique`

`upper`

`url_encode`

`values`

`without`

`withoutKey`