Latte フィルタ
**********
.[perex]
テンプレートでは、データを最終的な形に加工したり整形したりするのを助ける関数が使えます。これを*フィルタ*と呼びます。
.[table-latte-filters]
|## 変換
| `batch` | [線形のデータを表形式で出力する |#batch]
| `breakLines` | [すべての改行の前に HTML の改行を挿入する |#breakLines]
| `bytes` | [バイト単位のサイズを整形する |#bytes]
| `clamp` | [値を指定した範囲に収める |#clamp]
| `column` | [配列からひとつの列を取り出す |#column]
| `commas` | [配列をカンマでつなぐ |#commas]
| `limit` | [配列・文字列・イテレータの長さを制限する |#limit]
| `dataStream` | [Data URI プロトコルへの変換 |#dataStream]
| `date` | [日付と時刻を整形する |#date]
| `explode` | [区切り文字で文字列を配列に分割する |#explode]
| `filter` | [述語で反復可能な要素を絞り込む |#filter]
| `first` | [配列の最初の要素、または文字列の最初の文字を返す |#first]
| `group` | [さまざまな基準でデータをグループ化する |#group]
| `implode` | [配列を文字列に連結する |#implode]
| `indent` | [指定した数のタブでテキストを左からインデントする |#indent]
| `join` | [配列を文字列に連結する |#implode]
| `last` | [配列の最後の要素、または文字列の最後の文字を返す |#last]
| `length` | [文字列や配列の長さを返す |#length]
| `localDate` | [ロケールに従って日付と時刻を整形する |#localDate]
| `map` | [各要素にコールバックを適用する |#map]
| `number` | [数値を整形する |#number]
| `padLeft` | [文字列を左から一定の長さまで埋める |#padLeft]
| `padRight` | [文字列を右から一定の長さまで埋める |#padRight]
| `random` | [配列のランダムな要素、または文字列のランダムな文字を返す |#random]
| `repeat` | [文字列を繰り返す |#repeat]
| `replace` | [検索文字列の出現を置き換える |#replace]
| `replaceRE` | [正規表現にもとづいて出現を置き換える |#replaceRE]
| `reverse` | [UTF‑8 の文字列や配列を逆順にする |#reverse]
| `slice` | [配列や文字列の一部を取り出す |#slice]
| `sort` | [配列を並べ替える |#sort]
| `spaceless` | [空白を取り除く |#spaceless]。[spaceless |tags] タグと同様
| `split` | [区切り文字で文字列を配列に分割する |#explode]
| `strip` | [空白を取り除く |#spaceless]。`spaceless` の非推奨の別名
| `stripHtml` | [HTML タグを取り除き、HTML エンティティを文字に変換する |#stripHtml]
| `substr` | [文字列の一部を返す |#substr]
| `trim` | [先頭と末尾の空白などの文字を取り除く |#trim]
| `translate` | [ほかの言語への翻訳 |#translate]
| `truncate` | [単語を保ちながら長さを短くする |#truncate]
| `webalize` | [UTF‑8 の文字列を URL で使う形式に整える |#webalize]
.[table-latte-filters]
|## 大文字と小文字
| `capitalize` | [小文字にし、各単語の最初の文字を大文字にする |#capitalize]
| `firstLower` | [最初の文字を小文字にする |#firstLower]
| `firstUpper` | [最初の文字を大文字にする |#firstUpper]
| `lower` | [小文字に変換する |#lower]
| `upper` | [大文字に変換する |#upper]
.[table-latte-filters]
|## 丸め
| `ceil` | [数値を指定した精度で切り上げる |#ceil]
| `floor` | [数値を指定した精度で切り捨てる |#floor]
| `round` | [数値を指定した精度で四捨五入する |#round]
.[table-latte-filters]
|## HTML 属性
| `accept` | [スマート属性の新しい振る舞いを受け入れる |#accept]
| `toggle` | [HTML 属性の有無を切り替える |#toggle]
.[table-latte-filters]
|## エスケープ
| `escapeUrl` | [URL 内のパラメータをエスケープする |#escapeUrl]
| `noescape` | [変数をエスケープせずに出力する |#noescape]
| `query` | [URL のクエリ文字列を生成する |#query]
HTML(`escapeHtml` と `escapeHtmlComment`)、XML(`escapeXml`)、JavaScript(`escapeJs`)、CSS(`escapeCss`)、iCalendar(`escapeICal`)用のエスケープフィルタもあります。これらは[コンテキストに応じたエスケープ |safety-first#コンテキストに応じたエスケープ]のおかげで Latte 自身が使うので、あなたが書く必要はありません。
.[table-latte-filters]
|## セキュリティ
| `checkUrl` | [危険な入力から URL アドレスを浄化する |#checkUrl]
| `nocheck` | [URL の自動浄化を止める |#nocheck]
Latte は `src` と `href` 属性を[自動的にチェックする |safety-first#リンクのチェック]ので、`checkUrl` フィルタを使う必要はほとんどありません。
.[note]
組み込みフィルタはすべて UTF‑8 エンコーディングの文字列を前提としています。
使い方
===
フィルタはパイプ記号のあとに書きます(前に空白があってもかまいません)。
```latte
<h1>{$heading|upper}</h1>
```
フィルタは連ねられ、左から右の順に適用されます。
```latte
<h1>{$heading|lower|capitalize}</h1>
```
パラメータはフィルタ名のあとに、コロンかカンマで区切って書きます。
```latte
<h1>{$heading|truncate:20,''}</h1>
```
フィルタは式に対しても適用できます。
```latte
{var $name = ($title|upper) . ($subtitle|lower)}
```
[カスタムフィルタ|custom-filters]は次のように登録できます。
```php
$latte = new Latte\Engine;
$latte->addFilter('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));
```
テンプレートでは次のように呼び出します。
```latte
<p>{$text|shortify}</p>
<p>{$text|shortify:100}</p>
```
nullsafe フィルタ .{data-version:3.1.0}
-----------------------------------
`|` の代わりに `?|` を使うと、どのフィルタも nullsafe にできます。値が `null` ならフィルタは実行されず、`null` が返ります。連なりの後続のフィルタも飛ばされます。
これは、値が `null` のとき省略される HTML 属性と組み合わせると便利です。
```latte
<div title={$title?|upper}>
{* $title が null なら: <div> *}
{* $title が 'hello' なら: <div title="HELLO"> *}
```
フィルタ
====
accept .[filter]{data-version:3.1.0}
------------------------------------
このフィルタは [Latte 3.0 からの移行|cookbook/migration-from-latte-30]の際に、属性の振る舞いの変更を確認し受け入れたことを示すために使います。値は変更しません。
これは一時的な道具です。移行が終わって移行警告を無効にしたら、テンプレートからこのフィルタを削除してください。
batch(int $length, mixed $rest=null): Generator .[filter]
---------------------------------------------------------
線形のデータを表形式で出力するのを簡単にするフィルタです。指定した数の要素を持つ配列のジェネレータを返します。第 2 パラメータを渡すと、最後の行の足りない要素をそれで埋めます。
```latte
{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>
```
出力:
```latte
<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 |tags#{iterateWhile}] タグも参照してください。
breakLines .[filter]
--------------------
各改行文字の前に HTML の `<br>` タグを挿入します。
```latte
{var $s = "Text & with \n newline"}
{$s|breakLines} {* "Text & with <br>\n newline" を出力 *}
```
bytes(int $precision=2) .[filter]
---------------------------------
バイト単位のサイズを人が読みやすい形に整形します。[ロケール |develop#ロケール]が設定されていれば、それに対応する小数点と桁区切りが使われます。
```latte
{$size|bytes} {* 0 B, 1.25 GB, … *}
{$size|bytes:0} {* 10 B, 1 GB, … *}
```
ceil(int $precision=0) .[filter]
--------------------------------
数値を指定した精度で切り上げます。
```latte
{=3.4|ceil} {* 4 を出力 *}
{=135.22|ceil:1} {* 135.3 を出力 *}
{=135.22|ceil:3} {* 135.22 を出力 *}
```
[#floor]、[#round]も参照してください。
capitalize .[filter]
--------------------
各単語が大文字で始まり、残りの文字はすべて小文字になります。PHP の `mbstring` 拡張が必要です。
```latte
{='i like LATTE'|capitalize} {* 'I Like Latte' を出力 *}
```
[#firstLower]、[#firstUpper]、[#lower]、[#upper]も参照してください。
checkUrl .[filter]
------------------
URL の浄化を強制します。URL が安全なスキーム(`http`、`https`、`ftp`、`mailto`、`tel`、`sms`)を使っているか、相対リンクであるかを調べ、セキュリティ上の危険になり得る `javascript:` のようなスキームを遮ります。
```latte
{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>checked</a>
<a data-href={$link}>unchecked</a>
```
出力:
```latte
<a data-href="">checked</a>
<a data-href="javascript:window.close()">unchecked</a>
```
[#nocheck]も参照してください。
clamp(int|float $min, int|float $max) .[filter]
-----------------------------------------------
値を min から max までの範囲(両端を含む)に収めます。
```latte
{$level|clamp: 0, 255}
```
[関数 |functions#clamp()]としても存在します。
column(string|int|null $columnKey, string|int|null $indexKey=null) .[filter]{data-version:3.1.3}
------------------------------------------------------------------------------------------------
多次元配列からひとつの列 `$columnKey` の値を取り出し、新しい配列として返します。オブジェクトの配列に対して、プロパティの値を取り出すのにも使えます。
```latte
{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) .[filter]{data-version:3.1.3}
------------------------------------------------------------
配列の要素をカンマと空白(`', '`)でつなぎます。項目を人が読みやすい形で並べるのに便利な近道です。
```latte
{var $items = ['apples', 'oranges', 'bananas']}
{$items|commas}
{* 'apples, oranges, bananas' を出力 *}
```
最後の 2 項目のあいだに独自の区切りを指定することもできます。
```latte
{$items|commas: ' and '}
{* 'apples, oranges and bananas' を出力 *}
{=['PHP', 'JavaScript', 'Python']|commas: ', or '}
{* 'PHP, JavaScript, or Python' を出力 *}
```
[#implode]も参照してください。
dataStream(?string $type=null) .[filter]
----------------------------------------
内容を data URI スキームに変換します。これにより、外部ファイルへのリンクなしに画像を HTML や CSS に埋め込めます。`$type` が `null` なら MIME タイプは自動的に判別されます。
変数に画像が入っているとしましょう(`$img = Image::fromFile('image.gif')`)。そのとき、
```latte
<img src={$img|dataStream}>
```
たとえば次のように出力されます。
```latte
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
9TXL0Y4OHwAAAABJRU5ErkJggg==">
```
.[caution]
PHP の `fileinfo` 拡張が必要です。
date(string $format='j. n. Y') .[filter]
----------------------------------------
PHP の [php:date] 関数が使うマスクに従って日付と時刻を整形します。このフィルタは日付を UNIX タイムスタンプ、文字列、`DateTimeInterface`、`DateInterval` オブジェクトとして受け取れます。
```latte
{$today|date:'j. n. Y'}
```
[#localDate]も参照してください。
escapeUrl .[filter]
-------------------
変数を URL のパラメータとして使えるようエスケープします。
```latte
<a href="http://example.com/{$name|escapeUrl}">{$name}</a>
```
[#query]も参照してください。
explode(string $separator='') .[filter]
---------------------------------------
区切り文字で文字列を配列に分割します。`split` の別名です。
```latte
{='one,two,three'|explode:','} {* ['one', 'two', 'three'] を返す *}
```
区切り文字が空文字列(既定値)の場合、入力は 1 文字ずつに分割されます。
```latte
{='123'|explode} {* ['1', '2', '3'] を返す *}
```
別名 `split` も使えます。
```latte
{='1,2,3'|split:','} {* ['1', '2', '3'] を返す *}
```
[#implode]も参照してください。
filter(callable $predicate): iterable .[filter]{data-version:3.0.20}
--------------------------------------------------------------------
配列やイテレータの要素を絞り込み、述語が `true` を返したものだけを残します。キーは保持されます。
```latte
{foreach ($people|filter: fn($person) => $person->age >= 18) as $adult}
<p>{$adult->name}</p>
{/foreach}
```
first .[filter]
---------------
配列の最初の要素、または文字列の最初の文字を返します。
```latte
{=[1, 2, 3, 4]|first} {* 1 を出力 *}
{='abcd'|first} {* 'a' を出力 *}
```
[#last]、[#random]も参照してください。
floor(int $precision=0) .[filter]
---------------------------------
数値を指定した精度で切り捨てます。
```latte
{=3.5|floor} {* 3 を出力 *}
{=135.79|floor:1} {* 135.7 を出力 *}
{=135.79|floor:3} {* 135.79 を出力 *}
```
[#ceil]、[#round]も参照してください。
firstLower .[filter]{data-version:3.0.22}
-----------------------------------------
最初の文字を小文字にします。PHP の `mbstring` 拡張が必要です。
```latte
{='The Latte'|firstLower} {* 'the Latte' を出力 *}
```
[#capitalize]、[#firstUpper]、[#lower]、[#upper]も参照してください。
firstUpper .[filter]
--------------------
最初の文字を大文字にします。PHP の `mbstring` 拡張が必要です。
```latte
{='the latte'|firstUpper} {* 'The latte' を出力 *}
```
[#capitalize]、[#firstLower]、[#lower]、[#upper]も参照してください。
group(string|int|\Closure $by): iterable .[filter]{data-version:3.0.16}
-----------------------------------------------------------------------
このフィルタはさまざまな基準でデータをグループ化します。
この例では、テーブルの行を `categoryId` カラムでグループ化しています。出力はグループの反復可能な構造で、キーは `categoryId` カラムの値です。[詳しいガイドをご覧ください|cookbook/grouping]。
```latte
{foreach ($items|group: categoryId) as $categoryId => $categoryItems}
<ul>
{foreach $categoryItems as $item}
<li>{$item->name}</li>
{/foreach}
</ul>
{/foreach}
```
[#batch]、[group |functions#group()] 関数、[iterateWhile |tags#{iterateWhile}] タグも参照してください。
implode(string $glue='') .[filter]
----------------------------------
並びの要素を連結した文字列を返します。`join` の別名です。
```latte
{=[1, 2, 3]|implode} {* '123' を出力 *}
{=[1, 2, 3]|implode:'|'} {* '1|2|3' を出力 *}
```
別名 `join` も使えます。
```latte
{=[1, 2, 3]|join} {* '123' を出力 *}
```
[#commas]、[#explode]も参照してください。
indent(int $level=1, string $chars="\t") .[filter]
--------------------------------------------------
指定した数のタブ、または第 2 引数で指定した文字で、テキストを左からインデントします。空行はインデントされません。
```latte
<div>
{block |indent}
<p>Hello</p>
{/block}
</div>
```
出力:
```latte
<div>
<p>Hello</p>
</div>
```
last .[filter]
--------------
配列の最後の要素、または文字列の最後の文字を返します。
```latte
{=[1, 2, 3, 4]|last} {* 4 を出力 *}
{='abcd'|last} {* 'd' を出力 *}
```
[#first]、[#random]も参照してください。
length .[filter]
----------------
文字列や配列の長さを返します。
- 文字列の場合は UTF‑8 の文字数を返します
- 配列の場合は要素数を返します
- Countable インターフェースを実装したオブジェクトの場合は `count()` メソッドの戻り値を使います
- Traversable インターフェースを実装したオブジェクトの場合は `iterator_count()` 関数の戻り値を使います
```latte
{if ($users|length) > 10}
...
{/if}
```
localDate(?string $format=null, ?string $date=null, ?string $time=null) .[filter]
---------------------------------------------------------------------------------
[ロケール |develop#ロケール]に従って日付と時刻を整形し、言語や地域が違っても時刻データを一貫してローカライズされた形で表示できるようにします。このフィルタは日付を UNIX タイムスタンプ、文字列、`DateTimeInterface` オブジェクトとして受け取れます。
```latte
{$date|localDate} {* 2024年4月15日 *}
{$date|localDate: format: yM} {* 2024/4 *}
{$date|localDate: date: medium} {* 2024/04/15 *}
```
パラメータなしで使うと、後述の `long` の水準で日付を出力します。
**a) format を使う**
`format` パラメータは、時刻のどの要素を表示するかを表します。文字コードを使い、その繰り返しの回数が出力の幅に影響します。
| 年 | `y` / `yy` / `yyyy` | `2024` / `24` / `2024`
| 月 | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `Aug` / `August`
| 日 | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `Sun` / `Sunday`
| 時 | `j` / `H` / `h` | 推奨 / 24 時間制 / 12 時間制
| 分 | `m` / `mm` | `5` / `05` <small>(秒と組み合わせると 2 桁)</small>
| 秒 | `s` / `ss` | `8` / `08` <small>(分と組み合わせると 2 桁)</small>
format の中でのコードの順序は関係ありません。要素の順序はロケールの慣習に従って表示されるからです。つまり format はロケールに依存しません。たとえば format `yyyyMMMMd` は `en_US` ロケールでは `April 15, 2024` を、`cs_CZ` ロケールでは `15. dubna 2024` を出力します。
| ロケール: | cs_CZ | en_US
|---
| `format: 'dMy'` | 10. 8. 2024 | 8/10/2024
| `format: 'yM'` | 8/2024 | 8/2024
| `format: 'yyyyMMMM'` | srpen 2024 | August 2024
| `format: 'MMMM'` | srpen | August
| `format: 'jm'` | 17:22 | 5:22 PM
| `format: 'Hm'` | 17:22 | 17:22
| `format: 'hm'` | 5:22 odp. | 5:22 PM
**b) 定義済みのスタイルを使う**
`date` と `time` のパラメータは、日付と時刻をどれくらい詳しく表示するかを決めます。`full`、`long`、`medium`、`short` のいくつかの水準から選べます。日付だけ、時刻だけ、あるいは両方を表示できます。
| ロケール: | cs_CZ | en_US
|---
| `date: short` | 23.01.78 | 1/23/78
| `date: medium` | 23. 1. 1978 | Jan 23, 1978
| `date: long` | 23. ledna 1978 | January 23, 1978
| `date: full` | pondělí 23. ledna 1978 | Monday, January 23, 1978
| `time: short` | 8:30 | 8:30 AM
| `time: medium` | 8:30:59 | 8:30:59 AM
| `time: long` | 8:30:59 SEČ | 8:30:59 AM GMT+1
| `date: short, time: short` | 23.01.78 8:30 | 1/23/78, 8:30 AM
| `date: medium, time: short` | 23. 1. 1978 8:30 | Jan 23, 1978, 8:30 AM
| `date: long, time: short` | 23. ledna 1978 v 8:30 | January 23, 1978 at 8:30 AM
日付には接頭辞 `relative-`(たとえば `relative-short`)も使えます。現在に近い日付では `昨日`、`今日`、`明日` と表示し、それ以外は通常の方法で表示します。
```latte
{$date|localDate: date: relative-short} {* 昨日 *}
```
[#date]も参照してください。
lower .[filter]
---------------
文字列を小文字に変換します。PHP の `mbstring` 拡張が必要です。
```latte
{='LATTE'|lower} {* 'latte' を出力 *}
```
[#capitalize]、[#firstLower]、[#firstUpper]、[#upper]も参照してください。
map(callable $transformer): iterable .[filter]{data-version:3.1.6}
------------------------------------------------------------------
配列やイテレータの各要素をコールバックで変換し、新しいイテレータを返します。[#filter]フィルタと対になるものです。キーは保持されます。
```latte
{=($users|map: fn($user) => $user->name)|implode: ', '} {* John, Mary, Paul *}
```
[#filter]も参照してください。
nocheck .[filter]
-----------------
URL の自動浄化を止めます。Latte は URL が安全なスキーム(`http`、`https`、`ftp`、`mailto`、`tel`、`sms` など)を使っているか、相対リンクであるかを[自動的にチェックし |safety-first#リンクのチェック]、危険になり得るものを遮ります。
リンクが `javascript:` や `data:` のような別のスキームを使っていて、その内容に確信があるなら、`|nocheck` でチェックを無効にできます。
```latte
{var $link = 'javascript:window.close()'}
<a href={$link}>checked</a>
<a href={$link|nocheck}>unchecked</a>
```
出力:
```latte
<a href="">checked</a>
<a href="javascript:window.close()">unchecked</a>
```
[#checkUrl]も参照してください。
noescape .[filter]
------------------
自動エスケープを無効にします。
```latte
{var $trustedHtmlString = '<b>hello</b>'}
Escaped: {$trustedHtmlString}
Unescaped: {$trustedHtmlString|noescape}
```
出力:
```latte
Escaped: <b>hello</b>
Unescaped: <b>hello</b>
```
.[warning]
`noescape` フィルタの誤用は XSS 脆弱性につながります。何をしているのか、そして出力する文字列が信頼できる出所のものであることに**絶対の確信**がない限り、決して使わないでください。
number(int $decimals=0, string $decPoint='.', string $thousandsSep=',') .[filter]
---------------------------------------------------------------------------------
数値を指定した小数点以下の桁数に整形します。[ロケール |develop#ロケール]が設定されていれば、それに対応する小数点と桁区切りが使われます。
```latte
{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) .[filter]
--------------------------------
`format` パラメータを使うと、数値の見た目を必要に応じて正確に定義できます。これには[ロケール |develop#ロケール]の設定が必要です。format はいくつかの特別な文字から成り、完全な説明は "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns のドキュメントにあります。
- `0` 必須の桁。ゼロでも必ず表示されます
- `#` 省略可能な桁。その位置に実際に数字があるときだけ表示されます
- `@` 有効数字。一定の有効桁数で数値を表示するのに役立ちます
- `.` 小数点の位置を示します(国によってピリオドかカンマ)
- `,` 桁のグループ、たいていは千の位を区切るのに使います
- `%` 数値を 100 倍してパーセント記号を付けます
いくつか例を見てみましょう。最初の例では小数点以下 2 桁が必須で、2 つめでは省略可能です。3 つめの例は左右をゼロで埋め、4 つめは存在する桁だけを表示します。
```latte
{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 *}
```
有効数字は、小数点に関係なく何桁を表示するかを決め、必要なら丸めます。
```latte
{1234|number: '@@'} {* 1200 *}
{1234|number: '@@@'} {* 1230 *}
{1234|number: '@@@#'} {* 1234 *}
{1.2345|number: '@@@'} {* 1.23 *}
{0.00123|number: '@@'} {* 0.0012 *}
```
数値をパーセントとして表示する簡単な方法です。数値が 100 倍され、`%` 記号が付きます。
```latte
{0.1234|number: '#.##%'} {* 12.34% *}
```
正の数と負の数に別の format を定義でき、`;` の文字で区切ります。こうすれば、たとえば正の数に `+` 記号を付けて表示できます。
```latte
{42|number: '#.##;(#.##)'} {* 42 *}
{-42|number: '#.##;(#.##)'} {* (42) *}
{42|number: '+#.##;-#.##'} {* +42 *}
{-42|number: '+#.##;-#.##'} {* -42 *}
```
数値の実際の見た目は国の設定によって変わり得ることを覚えておいてください。たとえば国によっては小数点にピリオドではなくカンマを使います。このフィルタはそれを自動的に考慮するので、気にする必要はありません。
padLeft(int $length, string $append=' ') .[filter]
--------------------------------------------------
文字列や数値を、別の文字列で左から一定の長さまで埋めます。
```latte
{='hello'|padLeft: 10, '123'} {* '12312hello' を出力 *}
{=123|padLeft: 5, '0'} {* '00123' を出力 *}
```
padRight(int $length, string $append=' ') .[filter]
---------------------------------------------------
文字列や数値を、別の文字列で右から一定の長さまで埋めます。
```latte
{='hello'|padRight: 10, '123'} {* 'hello12312' を出力 *}
{=123|padRight: 5, '0'} {* '12300' を出力 *}
```
query .[filter]
---------------
URL のクエリ文字列を動的に生成します。
```latte
<a href="http://example.com/?{[name: 'John Doe', age: 43]|query}">click</a>
<a href="http://example.com/?search={$search|query}">search</a>
```
出力:
```latte
<a href="http://example.com/?name=John+Doe&age=43">click</a>
<a href="http://example.com/?search=Foo+Bar">search</a>
```
値が `null` のキーは省略されます。
[#escapeUrl]も参照してください。
random .[filter]
----------------
配列のランダムな要素、または文字列のランダムな文字を返します。
```latte
{=[1, 2, 3, 4]|random} {* たとえば 3 を出力 *}
{='abcd'|random} {* たとえば 'b' を出力 *}
```
[#first]、[#last]も参照してください。
repeat(int $count) .[filter]
----------------------------
文字列を指定回数繰り返します。
```latte
{='hello'|repeat: 3} {* 'hellohellohello' を出力 *}
```
replace(string|array $search, string|array $replace='') .[filter]
-----------------------------------------------------------------
検索文字列のすべての出現を置換文字列に置き換えます。
```latte
{='hello world'|replace: 'world', 'friend'} {* 'hello friend' を出力 *}
```
複数の置換を一度に行えます。
```latte
{='hello world'|replace: [h => l, l => h]} {* 'lehho worhd' を出力 *}
```
replaceRE(string $pattern, string $replacement='') .[filter]
------------------------------------------------------------
正規表現による検索と置換を行います。
```latte
{='hello world'|replaceRE: '/l.*/', 'l'} {* 'hel' を出力 *}
```
reverse(bool $preserveKeys=false) .[filter]
-------------------------------------------
指定した文字列や配列を逆順にします。
```latte
{var $s = 'Nette'}
{$s|reverse} {* 'etteN' を出力 *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse} {* ['e', 't', 't', 'e', 'N'] を返す *}
```
round(int $precision=0) .[filter]
---------------------------------
数値を指定した精度で四捨五入します。
```latte
{=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) .[filter]
------------------------------------------------------------------------
配列、文字列、イテレータの一部を取り出します。
```latte
{='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) .[filter]{data-version:3.1.3}
------------------------------------------------
配列、文字列、イテレータの長さを制限します。配列とイテレータではキーが保持されます。文字列では UTF-8 が尊重されます。
```latte
{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) .[filter]
-------------------------------------------------------------------------------------------------------------------
このフィルタは配列やイテレータの要素を並べ替え、連想キーを保持します。[ロケール |develop#ロケール]が設定されている場合、独自の比較関数を指定しない限り、その規則に従って並べ替えます。
```latte
{foreach ($names|sort) as $name}
...
{/foreach}
```
逆順に並べ替えた配列:
```latte
{foreach ($names|sort|reverse) as $name}
...
{/foreach}
```
並べ替えに独自の比較関数を指定できます(例は大きい順に並べ替える方法を示しています)。
```latte
{var $reverted = ($names|sort: fn($a, $b) => $b <=> $a)}
```
`|sort` フィルタはキーによる並べ替えもできます。
```latte
{foreach ($names|sort: byKey: true) as $name}
...
{/foreach}
```
表を特定の列で並べ替えたい場合は `by` パラメータが使えます。例の値 `'name'` は、`$item` が配列かオブジェクトかに応じて `$item->name` または `$item['name']` で並べ替えることを指定します。
```latte
{foreach ($items|sort: by: 'name') as $item}
{$item->name}
{/foreach}
```
並べ替えの基準となる値を決めるコールバック関数を定義することもできます。
```latte
{foreach ($items|sort: by: fn($item) => $item->category->name) as $item}
{$item->name}
{/foreach}
```
`byKey` パラメータも同じように使えます。
spaceless .[filter]
-------------------
出力から不要な空白を取り除きます。非推奨の別名 `strip` も使えますが、`spaceless` が推奨されます。
```latte
{block |spaceless}
<ul>
<li>Hello</li>
</ul>
{/block}
```
出力:
```latte
<ul><li>Hello</li></ul>
```
stripHtml .[filter]
-------------------
HTML をプレーンテキストに変換します。つまり HTML タグを取り除き、HTML エンティティをテキストの文字に変換します。
```latte
{='<p>one < two</p>'|stripHtml} {* 'one < two' を出力 *}
```
できあがったプレーンテキストには、当然ながら HTML タグを表す文字が含まれ得ます。たとえば `'<p>'|stripHtml` は `<p>` に変換されます。できあがったテキストを `|noescape` で出力してはいけません。セキュリティ脆弱性につながりかねません。
substr(int $start, ?int $length=null) .[filter]
-----------------------------------------------
文字列の一部を取り出します。このフィルタは [#slice]フィルタに置き換えられました。
```latte
{$string|substr: 1, 2}
```
toggle .[filter]{data-version:3.1.0}
------------------------------------
`toggle` フィルタは、真偽値にもとづいて属性の有無を制御します。値が真なら属性が現れ、偽なら属性はまるごと省かれます。
```latte
<div uk-grid={$isGrid|toggle}>
{* $isGrid が真なら: <div uk-grid> *}
{* $isGrid が偽なら: <div> *}
```
このフィルタは、HTML の真偽値属性と同じように有無の制御が必要な独自の属性や JavaScript ライブラリの属性に便利です。
このフィルタは HTML 属性の中でしか使えません。
translate(...$args) .[filter]
-----------------------------
式をほかの言語に翻訳します。このフィルタを使えるようにするには、[トランスレーターを設定する |develop#TranslatorExtension]必要があります。[翻訳用のタグ |tags#翻訳]も使えます。
```latte
<a href="basket">{='カート'|translate}</a>
<span>{$item|translate}</span>
```
trim(string $charlist=" \t\n\r\0\x0B\u{A0}") .[filter]
------------------------------------------------------
文字列の先頭と末尾から空白(またはほかの文字)を取り除きます。
```latte
{=' I like Latte. '|trim} {* 'I like Latte.' を出力 *}
{=' I like Latte.'|trim: '.'} {* ' I like Latte' を出力 *}
```
truncate(int $length, string $append='…') .[filter]
---------------------------------------------------
単語を丸ごと保とうとしながら、文字列を指定した最大長に切り詰めます。短くされた場合は末尾に省略記号を付けます(第 2 パラメータで変更できます)。
```latte
{var $title = 'Hello, how are you?'}
{$title|truncate:5} {* Hell… *}
{$title|truncate:17} {* Hello, how are… *}
{$title|truncate:30} {* Hello, how are you? *}
```
upper .[filter]
---------------
文字列を大文字に変換します。PHP の `mbstring` 拡張が必要です。
```latte
{='latte'|upper} {* 'LATTE' を出力 *}
```
[#capitalize]、[#firstLower]、[#firstUpper]、[#lower]も参照してください。
webalize .[filter]
------------------
UTF‑8 の文字列を URL で使う形式に整えます。
ASCII に変換します。空白をハイフンに変換します。英数字、アンダースコア、ハイフン以外の文字を取り除きます。小文字に変換します。先頭と末尾の空白も取り除きます。
```latte
{var $s = 'Our 10th product'}
{$s|webalize} {* 'our-10th-product' を出力 *}
```
.[caution]
[nette/utils|utils:] ライブラリが必要です。
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 & 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
パラメータは、時刻のどの要素を表示するかを表します。文字コードを使い、その繰り返しの回数が出力の幅に影響します。
| 年 |
y / yy / yyyy |
2024 / 24 / 2024 |
| 月 |
M / MM / MMM / MMMM |
8 / 08 / Aug / August |
| 日 |
d / dd / E / EEEE |
1 / 01 / Sun / Sunday |
| 時 |
j / H / h |
推奨 / 24 時間制 / 12 時間制 |
| 分 |
m / mm |
5 / 05 (秒と組み合わせると 2 桁) |
| 秒 |
s / ss |
8 / 08 (分と組み合わせると 2 桁) |
format
の中でのコードの順序は関係ありません。要素の順序はロケールの慣習に従って表示されるからです。つまり
format はロケールに依存しません。たとえば format yyyyMMMMd は en_US ロケールでは
April 15, 2024 を、cs_CZ ロケールでは 15. dubna 2024 を出力します。
| ロケール: |
cs_CZ |
en_US |
format: 'dMy' |
10. 8. 2024 |
8/10/2024 |
format: 'yM' |
8/2024 |
8/2024 |
format: 'yyyyMMMM' |
srpen 2024 |
August 2024 |
format: 'MMMM' |
srpen |
August |
format: 'jm' |
17:22 |
5:22 PM |
format: 'Hm' |
17:22 |
17:22 |
format: 'hm' |
5:22 odp. |
5:22 PM |
b) 定義済みのスタイルを使う
date と time
のパラメータは、日付と時刻をどれくらい詳しく表示するかを決めます。full、long、medium、short
のいくつかの水準から選べます。日付だけ、時刻だけ、あるいは両方を表示できます。
| ロケール: |
cs_CZ |
en_US |
date: short |
23.01.78 |
1/23/78 |
date: medium |
23. 1. 1978 |
Jan 23, 1978 |
date: long |
23. ledna 1978 |
January 23, 1978 |
date: full |
pondělí 23. ledna 1978 |
Monday, January 23, 1978 |
time: short |
8:30 |
8:30 AM |
time: medium |
8:30:59 |
8:30:59 AM |
time: long |
8:30:59 SEČ |
8:30:59 AM GMT+1 |
date: short, time: short |
23.01.78 8:30 |
1/23/78, 8:30 AM |
date: medium, time: short |
23. 1. 1978 8:30 |
Jan 23, 1978, 8:30 AM |
date: long, time: short |
23. ledna 1978 v 8:30 |
January 23, 1978 at 8:30 AM |
日付には接頭辞 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&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 < 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 ライブラリが必要です。