フィルタ

Twig に付随するテンプレートフィルタに加えて、Craft がいくつか独自のものを提供します。

atom

とりわけ Atom フィードで使用される、ISO-8601 タイムスタンプ(例:2019-01-29T10:00:00-08:00)に日付を変換します。

「camelCase」でフォーマットされた文字列を返します。

camel

配列に ArrayHelper::getColumn() を実行し、その結果を返します。

{{ entry.postDate|atom }}

ユーザーが優先する言語に応じて指定された通貨で、数値をフォーマットします。

{{ "foo bar"|camel }}
{# Outputs: fooBar #}

最後の引数に true を渡すと、フォーマットされる値が小数値(例:cents)を持たない場合、小数部の桁が削除されます。

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

column

利用可能な numberOptions は、こちらのリストを参照してください。

{{ 1000000|currency('USD') }} → $1,000,000.00
{{ 1000000|currency('USD', [], [], true) }} → $1,000,000

利用可能な textOptions は、こちらのリスト を参照してください。

{{ entry.postDate|date }} → Sep 26, 2018

currency( currency, numberOptions, textOptions, stripZeros )

タイムスタンプ、または、DateTime オブジェクトのフォーマットされた日付を出力します。

{{ entry.postDate|date('short') }} → 9/26/2018

date

format パラメータに値を渡すことで、詳細がどの程度提供されるかをカスタマイズできます。

{{ entry.postDate|date('short', locale='en-GB') }} → 26/9/2018

利用可能な format 値は、次の通りです。

{{ entry.postDate|date('Y-m-d') }} → 2018-09-26

使用される正確な時刻のフォーマットは、現在のアプリケーションのローケルに依存します。異なるローケルの時刻のフォーマットを使用したい場合、locale パラメータを利用します。

{{ entry.postDate|date('short', timezone='UTC') }} → 9/27/2018

PHP の date() ファンクションでサポートされるものと同じ フォーマットオプション を使用して、カスタムの日付フォーマットを渡すこともできます。

{{ entry.postDate|datetime }} → Sep 26, 2018, 5:00:00 PM

timezone パラメータを使用して、出力される時刻のタイムゾーンをカスタマイズできます。

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

タイムスタンプ、または、DateTime オブジェクトのフォーマットされた(時刻を含む)日付を出力します。

{{ entry.postDate|datetime('short', locale='en-GB') }} → 26/9/2018, 17:00

datetime

format パラメータに値を渡すことで、詳細がどの程度提供されるかをカスタマイズできます。

利用可能な format 値は、次の通りです。

duration

使用される正確な時刻のフォーマットは、現在のアプリケーションのローケルに依存します。異なるローケルの時刻のフォーマットを使用したい場合、locale パラメータを利用します。

{{ entry.postDate|datetime('short', timezone='UTC') }} → 9/27/2018, 12:00 AM

encenc

timezone パラメータを使用して、出力される時刻のタイムゾーンをカスタマイズできます。

DateInterval オブジェクトに craft\helpers\DateTimeHelper::humanDurationFromInterval() を実行します。

filesize

文字列を暗号化し、base64 エンコードします。

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

バイト数をより良い何かにフォーマットします。

filter

配列から空のエレメントを削除し、変更された配列を返します。

配列に craft\helpers\ArrayHelper::filterByValue() を実行します。

filterByValue

共通のプロパティに基づいて、配列の項目をグループ化します。

{{ "secure-string"|encenc }}

不正に変更されるべきではないフォームのデータを安全に渡すために、メッセージ認証コード(HMAC)の鍵付ハッシュを指定された文字列の先頭に追加します。

{% 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 %}

group

PHP スクリプトは、Security::validateData() を経由して値を検証できます。

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

を経由して、HTML の input 要素の id としてうまく動作するよう、文字列をフォーマットします。

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

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

配列に ArrayHelper::index() を実行します。

フォーマット実例
short9/26/2018
medium(デフォルト)Sep 26, 2018
longSeptember 26, 2018
fullWednesday, September 26, 2018
{% set name = 'input[name]' %}
<input type="text" name="{{ name }}" id="{{ name|id }}">

配列内の渡された値のインデックス、または、他の文字列に含まれる渡された文字列のインデックスを返します。(返される位置は、0 からはじまることに注意してください。)見つからなかった場合、代わりに -1 が返されます。

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

渡された配列内にある値だけを含む配列を返します。

{% 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 %}

hash

Twig の json_encode フィルタと同様ですが、引数 options がセットされておらず、レスポンスのコンテンツタイプが text/html または application/xhtml+xml の場合、デフォルトで JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_QUOT になります。

を通して、文字列を JSON デコードし配列にします。

id

「kebab-case」でフォーマットされた文字列を返します。

{% 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)
%}

ヒント:類推できない方のために、シシカバブの参照です。

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

文字列の最初の文字を小文字にします。

フォーマット実例
short9/26/2018, 5:00 PM
medium(デフォルト)Sep 26, 2018, 5:00:00 PM
longSeptember 26, 2018 at 5:00:00 PM PDT
fullWednesday, September 26, 2018 at 5:00:00 PM PDT

文字列に craft\helpers\Db::escapeParam() を実行します。

{{ "foo bar?"|kebab }}
{# Outputs: foo-bar #}

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

index

このフィルタは、2つの引数をサポートしています。

ArrayHelper::multisort() で配列をソートします。

indexOf

ユーザーが優先する言語に応じて、数値をフォーマットします。 craft\helpers\DateTimeHelper::humanDurationFromInterval()

{{ 1000000|number }} → 1,000,000
{{ 1000000|number(false) }} → 1000000

intersect

グループシンボル(例えば、英語のコンマ)を省略したい場合は、オプションで false を渡すことができます。

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

{{ content|parseRefs|raw }}

json_encode

リファレンスタグの文字列を解析します。

「PascalCase」(別名「UpperCamelCase」)でフォーマットされた文字列を返します。

json_decode

ユーザーが優先する言語に応じて、割合をフォーマットします。

kebab

文字列の一部を他のものに置き換えます。

ペアの検索 / 置換のオブジェクトを渡すことで、一度に複数のものを置き換えることができます。

{{ "foo bar"|pascal }}
{# Outputs: FooBar #}

または、一度に1つのものを置き換えることができます。

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

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

lcfirst

置換文字列の値の最初と最後にスラッシュを付けてマッチするものを検索することで、正規表現も利用できます。

literal

最も近い整数値に数を丸めます。

RSS フィードに必要な形式(D, d M Y H:i:s O)で日付を出力します。

format

「snake_case」でフォーマットされた文字列を返します。

タイムスタンプ、または、DateTime オブジェクトのフォーマットされた時刻を出力します。

multisort

format パラメータに値を渡すことで、詳細がどの程度提供されるかをカスタマイズできます。

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

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

number

利用可能な format 値は、次の通りです。

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

使用される正確な時刻のフォーマットは、現在のアプリケーションのローケルに依存します。異なるローケルの時刻のフォーマットを使用したい場合、locale パラメータを利用します。

{{ 42.1|round }}42
{{ 42.9|round }}43

parseRefs

timezone パラメータを使用して、出力される時刻のタイムゾーンをカスタマイズできます。

{{ entry.postDate|rss }}

pascal

経由で、人が読めるタイムスタンプとして日付をフォーマットします。

{{ "foo bar"|snake }}
{# Outputs: foo_bar #}

percentage

Craft::t() でメッセージを翻訳します。

{{ entry.postDate|time }} → 10:00:00 AM

replace

カテゴリの指定がない場合、デフォルトで site になります。

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

round

TIP

これがどのように機能するかの詳細については、静的メッセージの翻訳を参照してください。

文字列の最初の文字を大文字にします。

rss

文字列に含まれるそれぞれの単語の最初の文字を大文字にします。

配列に array_unique() を実行します。

snake

指定された配列のすべての値の配列を返しますが、カスタムキーは除かれます。

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

time

指定されたエレメントを除いた配列を返します。

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

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

timestamp

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.

ucfirst

Lowercases the first character of a string.

ucwords

Returns the number of elements in an array or string.

This works identically to Twig’s core length filter.

unique

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

values

Converts a value to lowercase.

This works identically to Twig’s core lower filter.

without

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.

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

This filter supports two arguments:

  • flavor は、'original'(デフォルト値)、'gfm'(GitHub-Flavored Markdown)、'gfm-comment'(改行が<br>に変換された GFM)、 または、'extra'(Markdown Extra)にできます。
  • inlineOnly は、<p> タグを除き、インライン要素だけを解析するかどうかを決定します。(デフォルトは 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).

{{ "Hello world"|t }}

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 arr1 = {foo: "Foo", bar: "Bar"} %}
{% set arr2 = arr1|values %}
{# arr2 = ["Foo", "Bar"] #}

pascal

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

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

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:

フォーマット実例
short5:00 PM
medium(デフォルト)5:00:00 PM
long5: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 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') %}