Фільтри для Latte

Фільтри – це функції, які змінюють або форматують дані до потрібної нам форми. Це короткий огляд вбудованих фільтрів, які доступні.

Існують також фільтри екранування для HTML (escapeHtml і escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) і iCalendar (escapeICal), які Latte використовує сам завдяки контекстно-залежному екрануванню, і вам не потрібно їх писати.

Latte перевіряє атрибути 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

Фільтр, який спрощує виведення лінійних даних у вигляді таблиці. Повертає масив із заданою кількістю елементів. Якщо ви вкажете другий параметр, він буде використаний для заповнення пропущених елементів в останньому рядку.

{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}    {* результати "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-адрес. Перевіряє, чи містить змінна веб-адресу (тобто протокол 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 strftime або date. Фільтр отримує дату у вигляді мітки часу UNIX, рядка або об'єкта типу DateTime.

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

escapeUrl

Екранує змінну, яка буде використана як параметр в URL.

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

Див. також query.

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

Дивіться також batch, функцію 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")

Відступає текст зліва на задану кількість табуляцій або інших символів, які ми вказуємо у другому необов'язковому аргументі. Порожні рядки не відступаються.

<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 автоматично перевіряє, чи містить змінна веб-адресу (тобто протокол 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'] *}

Фільтр фрагментів працює як PHP-функція array_slice для масивів і mb_substr для рядків з переходом на iconv_substr в режимі UTF-8.

Якщо початок невід'ємний, послідовність почнеться з цього початку у змінній. Якщо 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' у прикладі вказує, що сортування буде виконано за $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 = '…')

Скорочує рядок до максимально заданої довжини, але намагається зберегти цілі слова. Якщо рядок укорочено, додає в кінці багатокрапку (це можна змінити за допомогою другого параметра).

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