ラテフィルタ

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

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>

breakLines

すべての改行文字の前にHTMLの改行を挿入します。

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* outputs "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}         {* 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)

strftime あるいはdate の PHP 関数のオプションを使用して、指定した書式で日付を返します。フィルタは、UNIXタイムスタンプ、文字列、あるいはDateTime 型のオブジェクトとして日付を取得します。

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

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 も参照ください。

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}

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

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

配列をソートし、インデックスの関連付けを維持するフィルタです。

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

逆順にソートされた配列。

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

パラメータとして、独自の比較関数を渡すことができます。

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

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パッケージが必要です。