ラテフィルタ

フィルタは、データを好きな形に変更したり、フォーマットしたりする機能です。ここでは、内蔵されているフィルタの概要を説明します。

HTML (escapeHtml とescapeHtmlComment)、XML (escapeXml)、JavaScript (escapeJs)、CSS (escapeCss)、iCalendar (escapeICal)用のエスケープフィルタもあります。これらはコンテキストアウェアエスケープのおかげでラテが勝手に使ってくれるので、書く必要はありません。

src とhref の属性チェックは自動的に行われるため、checkUrl のフィルタを使用する必要はほとんどありません。

すべての組み込みフィルタは、UTF-8でエンコードされた文字列を扱うことができます。

使用方法

Latteでは，パイプ記号を使った記法でフィルタを呼び出すことができます（直前のスペースも可）．

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

フィルターは連結することができ、その場合、左から右の順に適用されます。

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

パラメータはコロンまたはカンマで区切られたフィルタ名の後に置かれます。

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

フィルタは式に対して適用することができる。

{var $name = ($title|upper) . ($subtitle|lower)}</h1>

カスタムフィルターは、このように登録することができます。

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

フィルター

batch (int $length, mixed $item): array

線形データの表形式でのリストアップを簡略化するフィルタです。これは、指定された数の項目を持つ配列の配列を返します。第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の改行を挿入します。

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* outputs "Text & with <br>\n newline" *}

bytes (int $precision=2)

バイト単位のサイズを人間が読める形に整形する。ロケールが設定されている場合は、対応する10進数と1000のセパレータが使用される。

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

ceil (int $precision=0)

数値を指定された精度で丸める。

{=3.4|ceil}         {* outputs 4      *}
{=135.22|ceil:1}    {* outputs 135.3  *}
{=135.22|ceil:3}    {* outputs 135.22 *}

floor,roundも参照のこと。

capitalize

値をタイトルケースに入れたものを返します。単語は大文字で始まり、残りの文字はすべて小文字になります。PHP 拡張モジュールが必要ですmbstring.

{='i like LATTE'|capitalize}  {* outputs 'I Like Latte' *}

firstUpper,lower,upper も参照ください。

checkUrl

URLのサニタイズ処理を行います。変数が Web URL (つまり HTTP/HTTPS プロトコル) を含んでいるかどうかをチェックし、セキュリティ上のリスクをもたらす可能性のあるリンクの書き込みを防止します。

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

関数としても存在する。

dataStream (string $mimetype=detect)

コンテンツをデータURIスキームに変換します。外部ファイルへのリンクを必要とせず、HTMLやCSSに画像を挿入するのに利用できます。

変数$img = Image::fromFile('obrazek.gif') に画像を入れておくとします。

<img src={$img|dataStream}>

例えば印刷します。

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

PHP 拡張機能が必要ですfileinfo.

date (string $format)

PHP の関数date で使われるマスクに従って、日付と時刻をフォーマットします。このフィルタは、UNIX タイムスタンプ形式、文字列、あるいはDateTimeInterface オブジェクトとして日付を受け取ります。

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

localDateも参照のこと。

escapeUrl

URLのパラメータとして使用される変数をエスケープします。

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

クエリも参照。

explode (string $separator='')

文字列を指定された区切り文字で分割し、文字列の配列を返します。split のエイリアス .

{='one,two,three'|explode:','}    {* returns ['one', 'two', 'three'] *}

デリミタが空文字列（デフォルト値）の場合、入力は個々の文字に分割されます。

{='123'|explode}                  {* returns ['1', '2', '3'] *}

また，split というエイリアスも使用できます．

{='1,2,3'|split:','}              {* returns ['1', '2', '3'] *}

implode も参照してください。

first

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

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

last,randomも参照のこと。

floor (int $precision=0)

与えられた精度で数値を丸める。

{=3.5|floor}        {* outputs 3      *}
{=135.79|floor:1}   {* outputs 135.7  *}
{=135.79|floor:3}   {* outputs 135.79 *}

ceil,roundも参照のこと。

firstUpper

値の最初の文字を大文字に変換します。PHP 拡張モジュールが必要ですmbstring.

{='the latte'|firstUpper}  {* outputs 'The latte' *}

capitalize,lower,upper も参照ください。

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

フィルタは、異なる基準に従ってデータをグループ化します。

この例では、テーブルの行はカラムcategoryId によってグループ化されています。出力は、列categoryId の値をキーとする配列の配列です。詳細な説明をお読みください。

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

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

implode (string $glue='')

配列中の文字列を連結した文字列を返します。join のエイリアス．

{=[1, 2, 3]|implode}      {* outputs '123' *}
{=[1, 2, 3]|implode:'|'}  {* outputs '1|2|3' *}

また、エイリアスとしてjoin を使用することもできます。

{=[1, 2, 3]|join}         {* outputs '123' *}

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

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

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

印刷します。

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

last

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

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

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

length

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

• 文字列の場合、UTF-8文字で長さを返します。
• 配列の場合は、項目の数を返します。
• Countableインタフェースを実装したオブジェクトの場合， count()の戻り値を使用します。
• IteratorAggregate インターフェースを実装したオブジェクトの場合、 iterator_count() の戻り値を使用する。

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

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

ロケールにしたがって日付と時刻をフォーマットし、異なる言語や地域間で時刻データの一貫したローカライズされた表示を保証します。このフィルタは、UNIXタイムスタンプ、文字列、DateTimeInterface オブジェクトとして日付を受け付けます。

{$date|localDate}                  {* 15. dubna 2024 *}
{$date|format: yM}                 {* 4/2024 *}
{$date|localDate: date: medium}    {* 15. 4. 2024 *}

このフィルターをパラメーターなしで使用すると、後で説明するように、長い書式レベルの日付が出力される。

a) フォーマットの使用

format パラメーターはどの時間要素を表示するかを指定します。これは文字コードを使用し、繰り返しの数が出力の幅に影響します：

構成要素の順序はロケールの規約に従って表示されるため、フォーマット内のコードの順序は問題ではない。したがって、書式はロケールに依存しない。たとえば、en_US ロケールではyyyyMMMMd という書式はApril 15, 2024 を出力しますが、cs_CZ ロケールでは15. dubna 2024 を出力します：

b) プリセットスタイルの使用

date とtime パラメータは、日付と時刻表示の詳細レベルを決定します。いくつかのレベルから選択できます：full long,medium,short 。日付のみ、時刻のみ、または両方を表示することができます：

日付には接頭辞relative- （例：relative-short ）を使うこともでき、現在に近い日付の場合はyesterday 、today 、tomorrow と表示される。それ以外の場合は標準的な方法で表示される。

{$date|localDate: date: relative-short}    {* yesterday *}

日付も参照。

lower

値を小文字に変換します。PHP 拡張モジュールmbstring が必要です。

{='LATTE'|lower}   {* outputs 'latte' *}

capitalize,firstUpper,upper も参照ください。

nocheck

自動的なURLサニタイズを防止します。Latte は変数に Web URL (すなわち HTTP/HTTPS プロトコル) が含まれているかどうかを自動的にチェックし、セキュリティ上のリスクがあるリンクの書き込みを防止します。

リンクに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 パラメータを使用すると、ニーズに合わせて数字の外観を正確に定義することができる。これにはロケールが必要である。この書式はいくつかの特殊文字で構成されており、その完全な説明はDecimalFormat

• <c id=6/> 必須桁。ゼロであっても常に表示される。
• # オプションの桁。数字がその位置に数字を持つ場合のみ表示される。
• @ 有意桁。有効桁数を指定して数値を表示するのに役立ちます。
• . 小数点の区切り位置を示すマーク（ロケールによってカンマまたはドット）。
• , 数桁のグループ（通常は数千）を区切るために使用します。
• % 数値に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% *}

正の数と負の数について、; 文字で区切った異なる書式を定義することができる。こうすることで、例えば正の数を+ 記号で表示することができる：

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

数字の実際の見た目は、ロケールの設定によって異なる可能性があることを覚えておいてください。例えば、ある国では小数点以下の区切り文字としてドットの代わりにカンマが使われます。このフィルターは自動的にこれを考慮しますので、心配する必要はありません。

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

指定された長さの文字列を、左から別の文字列で埋め尽くします。

{='hello'|padLeft: 10, '123'}  {* outputs '12312hello' *}

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

ある文字列を右から別の文字列で一定の長さになるように詰めます。

{='hello'|padRight: 10, '123'}  {* outputs 'hello12312' *}

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}    {* example output: 3 *}
{='abcd'|random}          {* example output: 'b' *}

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

repeat (int $count)

文字列をx回繰り返す。

{='hello'|repeat: 3}  {* outputs 'hellohellohello' *}

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

検索文字列を置換文字列で置き換えます。

{='hello world'|replace: 'world', 'friend'}  {* outputs 'hello friend' *}

一度に複数の置換を行うことができます。

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

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

正規表現にしたがって、すべての出現箇所を置き換えます。

{='hello world'|replaceRE: '/l.*/', 'l'}  {* outputs 'hel' *}

reverse

与えられた文字列または配列を反転させます。

{var $s = 'Nette'}
{$s|reverse}    {* outputs 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* returns ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

指定された精度で数値を丸めます。

{=3.4|round}        {* outputs 3      *}
{=3.5|round}        {* outputs 4      *}
{=135.79|round:1}   {* outputs 135.8  *}
{=135.79|round:3}   {* outputs 135.79 *}

ceil,floorも参照のこと。

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

配列または文字列のスライスを抽出します。

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

このスライスフィルタは、配列に対してはarray_slice PHP 関数として、文字列に対してはmb_substr として動作し、UTF-8 モードではiconv_substr にフォールバックします。

start が負でない場合、シーケンスは変数内のその位置から始まります。start が負の場合は、シーケンスは変数の終端からその距離だけ離れたところから始まります。

length が正の値であれば，シーケンスはその要素数までとなる。もし変数が length よりも短ければ、利用可能な変数の要素だけが存在することになります。もし length が負数なら、シーケンスは変数の終端からその数だけ要素を持つことになります。もし length が省略された場合は、offset から変数の終わりまでがシーケンスに含まれます。

Filter は、デフォルトで整数配列のキーを並べ替え、リセットします。この挙動は、preserveKeys を true に設定することで変更可能です。文字列のキーは、このパラメータに関係なく、常に保存されます。

sort (?Closure $comparison, 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' は、$row->name または $row['name']でソートされることを指定します。$row が配列かオブジェクトかによります：

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

また、ソートする値を決定するコールバック関数を定義することもできます：

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

byKey パラメータも同様に使用できます。

spaceless

出力から不要な空白を削除します。また、エイリアスstrip を使用することもできます。

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

印刷します。

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

stripHtml

HTMLをプレーンテキストに変換する。つまり、HTMLタグを削除し、HTMLの実体をテキストに変換します。

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

変換後のプレーンテキストには、当然ながらHTMLタグを表す文字が含まれます。例えば、'<p>'|stripHtml は、次のように変換されます。 <p>.セキュリティ上の脆弱性があるため、結果のテキストを|noescape で出力することは絶対に避けてください。

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

文字列のスライスを抽出する。このフィルタは、スライスフィルタに置き換えられました。

{$string|substr: 1, 2}

translate (string $message, …$args)

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

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

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

先頭と末尾の文字を除去します。デフォルトは空白文字です。

{='  I like Latte.  '|trim}    {* outputs 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* outputs '  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}  {* outputs 'LATTE' *}

capitalize,firstUpper,lower も参照ください。

webalize

ASCIIに変換する。

空白をハイフンに変換します。英数字、アンダースコア、ハイフンでない文字を削除します。小文字に変換します。また、先頭と末尾の空白を除去します。

{var $s = 'Our 10. product'}
{$s|webalize}    {* outputs 'our-10-product' *}

nette/utilsパッケージが必要です。