Фільтри 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

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

{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-адресу. Перевіряє, чи містить змінна веб-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. За допомогою нього можна вставляти зображення в 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 timestamp, як рядок або об'єкт типу 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")

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

<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 timestamp, рядок або об'єкт типу DateTimeInterface.

{$date|localDate}                  {* 15 квітня 2024 *}
{$date|format: yM}                 {* 4/2024 *}
{$date|localDate: date: medium}    {* 15. 4. 2024 *}

Якщо ви використовуєте фільтр без параметрів, дата буде виведена на рівні long, див. далі.

a) використання формату

Параметр format описує, які часові компоненти мають бути відображені. Він використовує для них літерні коди, кількість повторень яких впливає на ширину виводу:

Порядок кодів у форматі не має значення, оскільки порядок компонентів виводиться відповідно до звичаїв локалі. Таким чином, формат не залежить від неї. Наприклад, формат yyyyMMMMd у середовищі en_US виведе April 15, 2024, тоді як у середовищі uk_UA виведе 15 квітня 2024:

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 автоматично перевіряє, чи містить змінна веб-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× і додається знак відсотка

Розглянемо приклади. У першому прикладі два десяткові знаки є обов'язковими, у другому – необов'язковими. Третій приклад показує доповнення нулями зліва та справа, четвертий відображає лише існуючі цифри:

{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}">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}    {* виведе напр.: 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 для рядків з fallback на функцію iconv_substr у режимі UTF‑8.

Якщо 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->name або $item['name'], залежно від того, чи є $item масивом чи об'єктом:

{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}  {* виведе 'one < two' *}

Отриманий чистий текст може природно містити символи, які представляють HTML-теги, наприклад '<p>'|stripHtml перетвориться на <p>. У жодному разі не виводьте так отриманий текст з |noescape, оскільки це може призвести до виникнення діри в безпеці.

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

Витягує частину рядка. Цей фільтр було замінено фільтром slice.

{$string|substr: 1, 2}

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='…')

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

{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 = 'Наш 10-й продукт'}
{$s|webalize}   {* виведе 'nash-10-j-produkt' *}

Потребує бібліотеку nette/utils.