Фільтри для Latte
Фільтри – це функції, які змінюють або форматують дані до потрібної нам форми. Це короткий огляд вбудованих фільтрів, які доступні.
capitalize |
нижній регістр, перша буква кожного слова у верхньому регістрі |
firstUpper |
робить першу букву у верхньому регістрі |
lower |
робить рядок рядковим |
upper |
робить рядок у верхньому регістрі |
ceil |
округлює число в більший бік із заданою точністю |
floor |
округлює число в менший бік із заданою точністю |
round |
округлення числа до заданої точності |
escapeUrl |
екранує параметр в URL |
noescape |
друкує змінну без екранування |
query |
формує рядок запиту в URL |
Існують також фільтри екранування для HTML (escapeHtml
і
escapeHtmlComment
), XML (escapeXml
), JavaScript (escapeJs
), CSS (escapeCss
) і
iCalendar (escapeICal
), які Latte використовує сам завдяки контекстно-залежному
екрануванню, і вам не потрібно їх писати.
checkUrl |
Санує рядок для використання всередині атрибута href |
nocheck |
запобігає автоматичній санації URL |
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>
breakLines
Вставляє розриви рядків HTML перед усіма новими рядками.
{var $s = "Text & with \n newline"}
{$s|breakLines} {* результати "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} {* виводиться 4 *}
{=135.22|ceil:1} {* виводиться 135.3 *}
{=135.22|ceil:3} {* виводиться 135.22 *}
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' *}
floor (int precision = 0)
Округлює число до заданої точності.
{=3.5|floor} {* outputs 3 *}
{=135.79|floor:1} {* outputs 135.7 *}
{=135.79|floor:3} {* outputs 135.79 *}
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"
)
Відступає текст зліва на задану кількість табуляцій або інших символів, які ми вказуємо у другому необов'язковому аргументі. Порожні рядки не відступаються.
<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' *}
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&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' *}
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 *}
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
Фільтр, який сортує масив і зберігає зв'язок індексів.
{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 < 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.