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)}</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タグ <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' を出力 *}

参照 firstUpper, lower, upper。

checkUrl

URLアドレスのサニタイズを強制します。変数がWeb URL（つまりHTTP/HTTPSプロトコル）を含んでいるかを確認し、セキュリティリスクをもたらす可能性のあるリンクの出力を防ぎます。

{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>チェック済み</a>
<a data-href={$link}>未チェック</a>

出力：

<a data-href="">チェック済み</a>
<a data-href="javascript:window.close()">未チェック</a>

参照 nocheck。

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

値を指定された包括的な範囲minとmax内に制限します。

{$level|clamp: 0, 255}

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

dataStream (string $mimetype=detect)

コンテンツを data URI scheme に変換します。これにより、外部ファイルをリンクする必要なく、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>

参照 query。

explode (string $separator='')

区切り文字に基づいて文字列を配列に分割します。split のエイリアス。

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

区切り文字が空の文字列（デフォルト値）の場合、入力は個々の文字に分割されます：

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

エイリアス split を使用することもできます：

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

参照 implode。

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。

firstUpper

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

{='the latte'|firstUpper}  {* '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}

参照 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' を出力 *}

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}    {* 4 を出力 *}
{='abcd'|last}          {* '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}                  {* 2024年4月15日 *}
{$date|localDate: format: yM}      {* 2024/4 *}
{$date|localDate: date: medium}    {* 2024/04/15 *}

パラメータなしでフィルタを使用すると、日付は long レベルで表示されます（下記参照）。

a) フォーマットの使用

format パラメータは、表示する時間コンポーネントを記述します。文字コードを使用し、その繰り返し回数が出力の幅に影響します：

フォーマット内のコードの順序は関係ありません。コンポーネントの順序はロケールの慣習に従って表示されるためです。したがって、フォーマットはロケールに依存しません。例えば、フォーマット yyyyMMMMd は、en_US 環境では April 15, 2024 と表示されますが、ja_JP 環境では 2024年4月15日 と表示されます：

b) 事前定義されたスタイルの使用

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

日付については、さらにプレフィックス relative-（例：relative-short）を使用できます。これは、現在に近い日付に対して 昨日、今日、または 明日 を表示し、それ以外の場合は標準的な方法で表示します。

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

参照 date。

lower

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

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

参照 capitalize, firstUpper, upper。

nocheck

URLアドレスの自動サニタイズを防ぎます。Latteは 自動的にチェックし、変数がWeb URL（つまりHTTP/HTTPSプロトコル）を含んでいるかを確認し、セキュリティリスクをもたらす可能性のあるリンクの出力を防ぎます。

リンクが javascript: や data: などの他のスキームを使用しており、その内容に自信がある場合は、|nocheck を使用してチェックを無効にできます。

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

<a href={$link}>チェック済み</a>
<a href={$link|nocheck}>未チェック</a>

出力：

<a href="">チェック済み</a>
<a href="javascript:window.close()">未チェック</a>

参照 checkUrl。

noescape

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

{var $trustedHtmlString = '<b>hello</b>'}
エスケープ済み: {$trustedHtmlString}
エスケープなし: {$trustedHtmlString|noescape}

出力：

エスケープ済み: <b>hello</b>
エスケープなし: <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 ドキュメントにあります：

• 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% *}

正の数と負の数に対して異なるフォーマットを定義できます。これらは ; 記号で区切られます。このようにして、例えば、正の数に + 記号を表示するように設定できます：

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

数値の実際の外観は、国の設定によって異なる場合があることに注意してください。例えば、一部の国では、小数点区切り文字としてドットの代わりにカンマが使用されます。このフィルタはこれを自動的に考慮し、何も心配する必要はありません。

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

文字列を左から別の文字列で指定された長さにパディングします。

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

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

文字列を右から別の文字列で指定された長さにパディングします。

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

query

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

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

出力：

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

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

参照 escapeUrl。

random

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

{=[1, 2, 3, 4]|random}    {* 例：3 を出力 *}
{='abcd'|random}          {* 例：'b' を出力 *}

参照 first, last。

repeat (int $count)

文字列をx回繰り返します。

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

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

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

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

一度に複数の置換を実行することもできます：

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

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

置換を伴う正規表現検索を実行します。

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

reverse

指定された文字列または配列を反転します。

{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 として機能し、UTF‑8 モードでは iconv_substr 関数へのフォールバックがあります。

start が正の場合、シーケンスは配列/文字列の先頭からこの数だけオフセットされて開始します。負の場合、シーケンスは末尾からそれだけオフセットされて開始します。

length パラメータが指定され、正の場合、シーケンスにはその数の要素が含まれます。この関数に負の length パラメータが渡された場合、シーケンスには元の配列のすべての要素が含まれ、start 位置から開始し、配列の末尾から length 要素少ない位置で終了します。このパラメータを指定しない場合、シーケンスには元の配列のすべての要素が含まれ、start 位置から開始します。

デフォルトでは、フィルタは順序を変更し、配列の整数キーをリセットします。この動作は、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' の値は、$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 を使用することもできます。

{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 $offset, ?int $length=null)

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

{$string|substr: 1, 2}

translate (…$args)

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

<a href="basket">{='Košík'|translate}</a>  {* Assuming 'Košík' translates to 'Cart' *}
<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, firstUpper, lower。

webalize

UTF‑8文字列をURLで使用される形式に変換します。

ASCIIに変換されます。スペースをハイフンに変換します。英数字、アンダースコア、ハイフン以外の文字を除去します。小文字に変換します。先頭と末尾のスペースも除去します。

{var $s = 'Náš 10. produkt'}
{$s|webalize}   {* 'nas-10-produkt' を出力 *}

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