Фільтри для 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 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:','}    {* 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}

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 описує, які компоненти часу слід відображати. Він використовує літерні коди, де кількість повторень впливає на ширину виводу:

Порядок кодів у форматі не має значення, оскільки порядок компонентів буде відображено відповідно до умов локалізації. Таким чином, формат не залежить від локалі. Наприклад, формат yyyyMMMMd у локалі en_US виводить 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 автоматично перевіряє, чи містить змінна веб-адресу (тобто протокол 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 і додає знак відсотків

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

{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'] *}

Фільтр фрагментів працює як 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 (…$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.