Latte フィルタ

テンプレートでは、データを最終的な形に加工したり整形したりするのを助ける関数が使えます。これをフィルタと呼びます。

HTML（escapeHtml と escapeHtmlComment）、XML（escapeXml）、JavaScript（escapeJs）、CSS（escapeCss）、iCalendar（escapeICal）用のエスケープフィルタもあります。これらはコンテキストに応じたエスケープのおかげで Latte 自身が使うので、あなたが書く必要はありません。

Latte は src と href 属性を自動的にチェックするので、checkUrl フィルタを使う必要はほとんどありません。

組み込みフィルタはすべて UTF‑8 エンコーディングの文字列を前提としています。

使い方

フィルタはパイプ記号のあとに書きます（前に空白があってもかまいません）。

<h1>{$heading|upper}</h1>

フィルタは連ねられ、左から右の順に適用されます。

<h1>{$heading|lower|capitalize}</h1>

パラメータはフィルタ名のあとに、コロンかカンマで区切って書きます。

<h1>{$heading|truncate:20,''}</h1>

フィルタは式に対しても適用できます。

{var $name = ($title|upper) . ($subtitle|lower)}

カスタムフィルタは次のように登録できます。

$latte = new Latte\Engine;
$latte->addFilter('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));

テンプレートでは次のように呼び出します。

<p>{$text|shortify}</p>
<p>{$text|shortify:100}</p>

nullsafe フィルタ

| の代わりに ?| を使うと、どのフィルタも nullsafe にできます。値が null ならフィルタは実行されず、null が返ります。連なりの後続のフィルタも飛ばされます。

これは、値が null のとき省略される HTML 属性と組み合わせると便利です。

<div title={$title?|upper}>
{* $title が null なら: <div> *}
{* $title が 'hello' なら: <div title="HELLO"> *}

フィルタ

accept

このフィルタは Latte 3.0 からの移行の際に、属性の振る舞いの変更を確認し受け入れたことを示すために使います。値は変更しません。

これは一時的な道具です。移行が終わって移行警告を無効にしたら、テンプレートからこのフィルタを削除してください。

batch (int $length, mixed $rest=null): Generator

線形のデータを表形式で出力するのを簡単にするフィルタです。指定した数の要素を持つ配列のジェネレータを返します。第 2 パラメータを渡すと、最後の行の足りない要素をそれで埋めます。

{var $items = ['a', 'b', 'c', 'd', 'e']}
<table>
{foreach ($items|batch: 3, 'No item') as $row}
	<tr>
		{foreach $row as $column}
			<td>{$column}</td>
		{/foreach}
	</tr>
{/foreach}
</table>

出力:

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

groupと iterateWhile タグも参照してください。

breakLines

各改行文字の前に HTML の <br> タグを挿入します。

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* "Text &amp; with <br>\n newline" を出力 *}

bytes (int $precision=2)

バイト単位のサイズを人が読みやすい形に整形します。ロケールが設定されていれば、それに対応する小数点と桁区切りが使われます。

{$size|bytes}     {* 0 B, 1.25 GB, … *}
{$size|bytes:0}   {* 10 B, 1 GB, … *}

ceil (int $precision=0)

数値を指定した精度で切り上げます。

{=3.4|ceil}         {* 4 を出力      *}
{=135.22|ceil:1}    {* 135.3 を出力  *}
{=135.22|ceil:3}    {* 135.22 を出力 *}

floor、roundも参照してください。

capitalize

各単語が大文字で始まり、残りの文字はすべて小文字になります。PHP の mbstring 拡張が必要です。

{='i like LATTE'|capitalize}  {* 'I Like Latte' を出力 *}

firstLower、firstUpper、lower、upperも参照してください。

checkUrl

URL の浄化を強制します。URL が安全なスキーム（http、https、ftp、mailto、tel、sms）を使っているか、相対リンクであるかを調べ、セキュリティ上の危険になり得る javascript: のようなスキームを遮ります。

{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>checked</a>
<a data-href={$link}>unchecked</a>

出力:

<a data-href="">checked</a>
<a data-href="javascript:window.close()">unchecked</a>

nocheckも参照してください。

clamp (int|float $min, int|float $max)

値を min から max までの範囲（両端を含む）に収めます。

{$level|clamp: 0, 255}

関数としても存在します。

column (string|int|null $columnKey, string|int|null $indexKey=null)

多次元配列からひとつの列 $columnKey の値を取り出し、新しい配列として返します。オブジェクトの配列に対して、プロパティの値を取り出すのにも使えます。

{var $users = [
	[id: 30, name: 'John', age: 30],
	[id: 32, name: 'Jane', age: 25],
	[id: 33, age: 35],
]}

{$users|column: 'name'}
{* ['John', 'Jane'] を返す *}

{$users|column: 'name', 'id'}
{* [30 => 'John', 32 => 'Jane'] を返す *}

列のキーとして null を渡すと、$indexKey に従って配列のインデックスを付け直します。

commas (?string $lastGlue=null)

配列の要素をカンマと空白（', '）でつなぎます。項目を人が読みやすい形で並べるのに便利な近道です。

{var $items = ['apples', 'oranges', 'bananas']}
{$items|commas}
{* 'apples, oranges, bananas' を出力 *}

最後の 2 項目のあいだに独自の区切りを指定することもできます。

{$items|commas: ' and '}
{* 'apples, oranges and bananas' を出力 *}

{=['PHP', 'JavaScript', 'Python']|commas: ', or '}
{* 'PHP, JavaScript, or Python' を出力 *}

implodeも参照してください。

dataStream (?string $type=null)

内容を data URI スキームに変換します。これにより、外部ファイルへのリンクなしに画像を HTML や CSS に埋め込めます。$type が null なら MIME タイプは自動的に判別されます。

変数に画像が入っているとしましょう（$img = Image::fromFile('image.gif')）。そのとき、

<img src={$img|dataStream}>

たとえば次のように出力されます。

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
9TXL0Y4OHwAAAABJRU5ErkJggg==">

PHP の fileinfo 拡張が必要です。

date (string $format='j. n. Y')

PHP の date 関数が使うマスクに従って日付と時刻を整形します。このフィルタは日付を UNIX タイムスタンプ、文字列、DateTimeInterface、DateInterval オブジェクトとして受け取れます。

{$today|date:'j. n. Y'}

localDateも参照してください。

escapeUrl

変数を URL のパラメータとして使えるようエスケープします。

<a href="http://example.com/{$name|escapeUrl}">{$name}</a>

queryも参照してください。

explode (string $separator='')

区切り文字で文字列を配列に分割します。split の別名です。

{='one,two,three'|explode:','}    {* ['one', 'two', 'three'] を返す *}

区切り文字が空文字列（既定値）の場合、入力は 1 文字ずつに分割されます。

{='123'|explode}                  {* ['1', '2', '3'] を返す *}

別名 split も使えます。

{='1,2,3'|split:','}              {* ['1', '2', '3'] を返す *}

implodeも参照してください。

filter (callable $predicate): iterable

配列やイテレータの要素を絞り込み、述語が true を返したものだけを残します。キーは保持されます。

{foreach ($people|filter: fn($person) => $person->age >= 18) as $adult}
	<p>{$adult->name}</p>
{/foreach}

first

配列の最初の要素、または文字列の最初の文字を返します。

{=[1, 2, 3, 4]|first}    {* 1 を出力 *}
{='abcd'|first}          {* 'a' を出力 *}

last、randomも参照してください。

floor (int $precision=0)

数値を指定した精度で切り捨てます。

{=3.5|floor}        {* 3 を出力      *}
{=135.79|floor:1}   {* 135.7 を出力  *}
{=135.79|floor:3}   {* 135.79 を出力 *}

ceil、roundも参照してください。

firstLower

最初の文字を小文字にします。PHP の mbstring 拡張が必要です。

{='The Latte'|firstLower}  {* 'the Latte' を出力 *}

capitalize、firstUpper、lower、upperも参照してください。

firstUpper

最初の文字を大文字にします。PHP の mbstring 拡張が必要です。

{='the latte'|firstUpper}  {* 'The latte' を出力 *}

capitalize、firstLower、lower、upperも参照してください。

group (string|int|\Closure $by): iterable

このフィルタはさまざまな基準でデータをグループ化します。

この例では、テーブルの行を categoryId カラムでグループ化しています。出力はグループの反復可能な構造で、キーは categoryId カラムの値です。詳しいガイドをご覧ください。

{foreach ($items|group: categoryId) as $categoryId => $categoryItems}
    <ul>
        {foreach $categoryItems as $item}
            <li>{$item->name}</li>
        {/foreach}
    </ul>
{/foreach}

batch、group 関数、iterateWhile タグも参照してください。

implode (string $glue='')

並びの要素を連結した文字列を返します。join の別名です。

{=[1, 2, 3]|implode}      {* '123' を出力 *}
{=[1, 2, 3]|implode:'|'}  {* '1|2|3' を出力 *}

別名 join も使えます。

{=[1, 2, 3]|join}         {* '123' を出力 *}

commas、explodeも参照してください。

indent (int $level=1, string $chars="\t")

指定した数のタブ、または第 2 引数で指定した文字で、テキストを左からインデントします。空行はインデントされません。

<div>
{block |indent}
<p>Hello</p>
{/block}
</div>

出力:

<div>
	<p>Hello</p>
</div>

last

配列の最後の要素、または文字列の最後の文字を返します。

{=[1, 2, 3, 4]|last}    {* 4 を出力 *}
{='abcd'|last}          {* 'd' を出力 *}

first、randomも参照してください。

length

文字列や配列の長さを返します。

• 文字列の場合は UTF‑8 の文字数を返します
• 配列の場合は要素数を返します
• Countable インターフェースを実装したオブジェクトの場合は count() メソッドの戻り値を使います
• Traversable インターフェースを実装したオブジェクトの場合は iterator_count() 関数の戻り値を使います

{if ($users|length) > 10}
	...
{/if}

localDate (?string $format=null, ?string $date=null, ?string $time=null)

ロケールに従って日付と時刻を整形し、言語や地域が違っても時刻データを一貫してローカライズされた形で表示できるようにします。このフィルタは日付を UNIX タイムスタンプ、文字列、DateTimeInterface オブジェクトとして受け取れます。

{$date|localDate}                  {* 2024年4月15日 *}
{$date|localDate: format: yM}      {* 2024/4 *}
{$date|localDate: date: medium}    {* 2024/04/15 *}

パラメータなしで使うと、後述の long の水準で日付を出力します。

a) format を使う

format パラメータは、時刻のどの要素を表示するかを表します。文字コードを使い、その繰り返しの回数が出力の幅に影響します。

format の中でのコードの順序は関係ありません。要素の順序はロケールの慣習に従って表示されるからです。つまり format はロケールに依存しません。たとえば format yyyyMMMMd は en_US ロケールでは April 15, 2024 を、cs_CZ ロケールでは 15. dubna 2024 を出力します。

b) 定義済みのスタイルを使う

date と time のパラメータは、日付と時刻をどれくらい詳しく表示するかを決めます。full、long、medium、short のいくつかの水準から選べます。日付だけ、時刻だけ、あるいは両方を表示できます。

日付には接頭辞 relative-（たとえば relative-short）も使えます。現在に近い日付では 昨日、今日、明日 と表示し、それ以外は通常の方法で表示します。

{$date|localDate: date: relative-short}    {* 昨日 *}

dateも参照してください。

lower

文字列を小文字に変換します。PHP の mbstring 拡張が必要です。

{='LATTE'|lower}   {* 'latte' を出力 *}

capitalize、firstLower、firstUpper、upperも参照してください。

map (callable $transformer): iterable

配列やイテレータの各要素をコールバックで変換し、新しいイテレータを返します。filterフィルタと対になるものです。キーは保持されます。

{=($users|map: fn($user) => $user->name)|implode: ', '}   {* John, Mary, Paul *}

filterも参照してください。

nocheck

URL の自動浄化を止めます。Latte は URL が安全なスキーム（http、https、ftp、mailto、tel、sms など）を使っているか、相対リンクであるかを自動的にチェックし、危険になり得るものを遮ります。

リンクが javascript: や data: のような別のスキームを使っていて、その内容に確信があるなら、|nocheck でチェックを無効にできます。

{var $link = 'javascript:window.close()'}

<a href={$link}>checked</a>
<a href={$link|nocheck}>unchecked</a>

出力:

<a href="">checked</a>
<a href="javascript:window.close()">unchecked</a>

checkUrlも参照してください。

noescape

自動エスケープを無効にします。

{var $trustedHtmlString = '<b>hello</b>'}
Escaped: {$trustedHtmlString}
Unescaped: {$trustedHtmlString|noescape}

出力:

Escaped: <b>hello</b>
Unescaped: <b>hello</b>

noescape フィルタの誤用は XSS 脆弱性につながります。何をしているのか、そして出力する文字列が信頼できる出所のものであることに絶対の確信がない限り、決して使わないでください。

number (int $decimals=0, string $decPoint='.', string $thousandsSep=',')

数値を指定した小数点以下の桁数に整形します。ロケールが設定されていれば、それに対応する小数点と桁区切りが使われます。

{1234.20|number}              {* 1,234 *}
{1234.20|number:1}            {* 1,234.2 *}
{1234.20|number:2}            {* 1,234.20 *}
{1234.20|number:2, ',', ' '}  {* 1 234,20 *}

number (string $format)

format パラメータを使うと、数値の見た目を必要に応じて正確に定義できます。これにはロケールの設定が必要です。format はいくつかの特別な文字から成り、完全な説明は DecimalFormat のドキュメントにあります。

• 0 必須の桁。ゼロでも必ず表示されます
• # 省略可能な桁。その位置に実際に数字があるときだけ表示されます
• @ 有効数字。一定の有効桁数で数値を表示するのに役立ちます
• . 小数点の位置を示します（国によってピリオドかカンマ）
• , 桁のグループ、たいていは千の位を区切るのに使います
• % 数値を 100 倍してパーセント記号を付けます

いくつか例を見てみましょう。最初の例では小数点以下 2 桁が必須で、2 つめでは省略可能です。3 つめの例は左右をゼロで埋め、4 つめは存在する桁だけを表示します。

{1234.5|number: '#,##0.00'}     {* 1,234.50 *}
{1234.5|number: '#,##0.##'}     {* 1,234.5 *}
{1.23  |number: '000.000'}      {* 001.230 *}
{1.2   |number: '##.##'}        {* 1.2 *}

有効数字は、小数点に関係なく何桁を表示するかを決め、必要なら丸めます。

{1234|number: '@@'}             {* 1200 *}
{1234|number: '@@@'}            {* 1230 *}
{1234|number: '@@@#'}           {* 1234 *}
{1.2345|number: '@@@'}          {* 1.23 *}
{0.00123|number: '@@'}          {* 0.0012 *}

数値をパーセントとして表示する簡単な方法です。数値が 100 倍され、% 記号が付きます。

{0.1234|number: '#.##%'}        {* 12.34% *}

正の数と負の数に別の format を定義でき、; の文字で区切ります。こうすれば、たとえば正の数に + 記号を付けて表示できます。

{42|number: '#.##;(#.##)'}      {* 42 *}
{-42|number: '#.##;(#.##)'}     {* (42) *}
{42|number: '+#.##;-#.##'}      {* +42 *}
{-42|number: '+#.##;-#.##'}     {* -42 *}

数値の実際の見た目は国の設定によって変わり得ることを覚えておいてください。たとえば国によっては小数点にピリオドではなくカンマを使います。このフィルタはそれを自動的に考慮するので、気にする必要はありません。

padLeft (int $length, string $append=' ')

文字列や数値を、別の文字列で左から一定の長さまで埋めます。

{='hello'|padLeft: 10, '123'}  {* '12312hello' を出力 *}
{=123|padLeft: 5, '0'}         {* '00123' を出力 *}

padRight (int $length, string $append=' ')

文字列や数値を、別の文字列で右から一定の長さまで埋めます。

{='hello'|padRight: 10, '123'}  {* 'hello12312' を出力 *}
{=123|padRight: 5, '0'}         {* '12300' を出力 *}

query

URL のクエリ文字列を動的に生成します。

<a href="http://example.com/?{[name: 'John Doe', age: 43]|query}">click</a>
<a href="http://example.com/?search={$search|query}">search</a>

出力:

<a href="http://example.com/?name=John+Doe&amp;age=43">click</a>
<a href="http://example.com/?search=Foo+Bar">search</a>

値が null のキーは省略されます。

escapeUrlも参照してください。

random

配列のランダムな要素、または文字列のランダムな文字を返します。

{=[1, 2, 3, 4]|random}    {* たとえば 3 を出力 *}
{='abcd'|random}          {* たとえば 'b' を出力 *}

first、lastも参照してください。

repeat (int $count)

文字列を指定回数繰り返します。

{='hello'|repeat: 3}  {* 'hellohellohello' を出力 *}

replace (string|array $search, string|array $replace='')

検索文字列のすべての出現を置換文字列に置き換えます。

{='hello world'|replace: 'world', 'friend'}  {* 'hello friend' を出力 *}

複数の置換を一度に行えます。

{='hello world'|replace: [h => l, l => h]}  {* 'lehho worhd' を出力 *}

replaceRE (string $pattern, string $replacement='')

正規表現による検索と置換を行います。

{='hello world'|replaceRE: '/l.*/', 'l'}  {* 'hel' を出力 *}

reverse (bool $preserveKeys=false)

指定した文字列や配列を逆順にします。

{var $s = 'Nette'}
{$s|reverse}    {* 'etteN' を出力 *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* ['e', 't', 't', 'e', 'N'] を返す *}

round (int $precision=0)

数値を指定した精度で四捨五入します。

{=3.4|round}        {* 3 を出力      *}
{=3.5|round}        {* 4 を出力      *}
{=135.79|round:1}   {* 135.8 を出力  *}
{=135.79|round:3}   {* 135.79 を出力 *}

ceil、floorも参照してください。

slice (int $start, ?int $length=null, bool $preserveKeys=false)

配列、文字列、イテレータの一部を取り出します。

{='hello'|slice: 1, 2}           {* 'el' を出力 *}
{=['a', 'b', 'c']|slice: 1, 2}   {* ['b', 'c'] を出力 *}

このフィルタは、配列に対しては PHP の array_slice、文字列に対しては mb_substr のように動きます。イテレータに対してはジェネレータを返し、要素は元から順に取り出され、上限に達した時点で読み取りが止まります。イテレータ全体がメモリに読み込まれることはありません。

start が非負なら、配列や文字列の先頭からそのオフセットの位置から始まります。start が負なら、末尾からその分だけ手前から始まります。

length が指定されていて正なら、最大でその数の要素を含みます。入力が length より短ければ、利用できる要素だけが含まれます。length が指定されていて負なら、入力の末尾からその数だけ手前で終わります。省略した場合は、start から入力の末尾までのすべてが含まれます。

既定では、このフィルタは整数の配列キーを並べ直してリセットします。この振る舞いは preserveKeys を true にすると変えられます。文字列のキーは、このパラメータに関係なく常に保持されます。

limitも参照してください。

limit (int $length)

配列、文字列、イテレータの長さを制限します。配列とイテレータではキーが保持されます。文字列では UTF-8 が尊重されます。

{foreach ($items|limit: 5) as $item}
	...
{/foreach}

{$text|limit: 100}

sort (?Closure $comparison=null, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false)

このフィルタは配列やイテレータの要素を並べ替え、連想キーを保持します。ロケールが設定されている場合、独自の比較関数を指定しない限り、その規則に従って並べ替えます。

{foreach ($names|sort) as $name}
	...
{/foreach}

逆順に並べ替えた配列:

{foreach ($names|sort|reverse) as $name}
	...
{/foreach}

並べ替えに独自の比較関数を指定できます（例は大きい順に並べ替える方法を示しています）。

{var $reverted = ($names|sort: fn($a, $b) => $b <=> $a)}

|sort フィルタはキーによる並べ替えもできます。

{foreach ($names|sort: byKey: true) as $name}
	...
{/foreach}

表を特定の列で並べ替えたい場合は by パラメータが使えます。例の値 'name' は、$item が配列かオブジェクトかに応じて $item->name または $item['name'] で並べ替えることを指定します。

{foreach ($items|sort: by: 'name') as $item}
	{$item->name}
{/foreach}

並べ替えの基準となる値を決めるコールバック関数を定義することもできます。

{foreach ($items|sort: by: fn($item) => $item->category->name) as $item}
	{$item->name}
{/foreach}

byKey パラメータも同じように使えます。

spaceless

出力から不要な空白を取り除きます。非推奨の別名 strip も使えますが、spaceless が推奨されます。

{block |spaceless}
	<ul>
		<li>Hello</li>
	</ul>
{/block}

出力:

<ul><li>Hello</li></ul>

stripHtml

HTML をプレーンテキストに変換します。つまり HTML タグを取り除き、HTML エンティティをテキストの文字に変換します。

{='<p>one &lt; two</p>'|stripHtml}  {* 'one < two' を出力 *}

できあがったプレーンテキストには、当然ながら HTML タグを表す文字が含まれ得ます。たとえば '<p>'|stripHtml は <p> に変換されます。できあがったテキストを |noescape で出力してはいけません。セキュリティ脆弱性につながりかねません。

substr (int $start, ?int $length=null)

文字列の一部を取り出します。このフィルタは sliceフィルタに置き換えられました。

{$string|substr: 1, 2}

toggle

toggle フィルタは、真偽値にもとづいて属性の有無を制御します。値が真なら属性が現れ、偽なら属性はまるごと省かれます。

<div uk-grid={$isGrid|toggle}>
{* $isGrid が真なら: <div uk-grid> *}
{* $isGrid が偽なら: <div> *}

このフィルタは、HTML の真偽値属性と同じように有無の制御が必要な独自の属性や JavaScript ライブラリの属性に便利です。

このフィルタは HTML 属性の中でしか使えません。

translate (…$args)

式をほかの言語に翻訳します。このフィルタを使えるようにするには、トランスレーターを設定する必要があります。翻訳用のタグも使えます。

<a href="basket">{='カート'|translate}</a>
<span>{$item|translate}</span>

trim (string $charlist=" \t\n\r\0\x0B\u{A0}")

文字列の先頭と末尾から空白（またはほかの文字）を取り除きます。

{='  I like Latte.  '|trim}    {* 'I like Latte.' を出力 *}
{='  I like Latte.'|trim: '.'} {* '  I like Latte' を出力 *}

truncate (int $length, string $append='…')

単語を丸ごと保とうとしながら、文字列を指定した最大長に切り詰めます。短くされた場合は末尾に省略記号を付けます（第 2 パラメータで変更できます）。

{var $title = 'Hello, how are you?'}
{$title|truncate:5}  {* Hell…                *}
{$title|truncate:17} {* Hello, how are…      *}
{$title|truncate:30} {* Hello, how are you?  *}

upper

文字列を大文字に変換します。PHP の mbstring 拡張が必要です。

{='latte'|upper}  {* 'LATTE' を出力 *}

capitalize、firstLower、firstUpper、lowerも参照してください。

webalize

UTF‑8 の文字列を URL で使う形式に整えます。

ASCII に変換します。空白をハイフンに変換します。英数字、アンダースコア、ハイフン以外の文字を取り除きます。小文字に変換します。先頭と末尾の空白も取り除きます。

{var $s = 'Our 10th product'}
{$s|webalize}   {* 'our-10th-product' を出力 *}

nette/utils ライブラリが必要です。