Фильтры 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 |
очищает URL-адрес от опасных входных данных |
nocheck |
предотвращает автоматическую очистку URL-адреса |
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 & 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-адрес. Проверяет, содержит ли переменная веб-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' *}
floor (int $precision=0)
Округляет число вниз до заданной точности.
{=3.5|floor} {* выводит 3 *}
{=135.79|floor:1} {* выводит 135.7 *}
{=135.79|floor:3} {* выводит 135.79 *}
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' *}
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
, см. далее.
а) использование формата
Параметр format
описывает, какие компоненты времени должны
отображаться. Для них используются буквенные коды, количество
повторений которых влияет на ширину вывода:
год | y / yy / yyyy |
2024 / 24 / 2024 |
месяц | M / MM / MMM / MMMM |
8 / 08 / авг / август |
день | d / dd / E / EEEE |
1 / 01 / вс / воскресенье |
час | j / H / h |
предпочтительный / 24-часовой / 12-часовой |
минута | m / mm |
5 / 05 (2 цифры в сочетании с секундами) |
секунда | s / ss |
8 / 08 (2 цифры в сочетании с минутами) |
Порядок кодов в формате не имеет значения, так как порядок
компонентов выводится в соответствии с обычаями локали. Таким образом,
формат не зависит от нее. Например, формат yyyyMMMMd
в среде
en_US
выведет April 15, 2024
, тогда как в среде cs_CZ
выведет
15. dubna 2024
:
locale: | cs_CZ | en_US |
---|---|---|
format: 'dMy' |
10. 8. 2024 | 8/10/2024 |
format: 'yM' |
8/2024 | 8/2024 |
format: 'yyyyMMMM' |
srpen 2024 | August 2024 |
format: 'MMMM' |
srpen | August |
format: 'jm' |
17:22 | 5:22 PM |
format: 'Hm' |
17:22 | 17:22 |
format: 'hm' |
5:22 odp. | 5:22 PM |
б) использование предустановленных стилей
Параметры date
и time
определяют, насколько подробно
должны выводиться дата и время. Вы можете выбрать из нескольких
уровней: full
, long
, medium
, short
. Можно вывести
только дату, только время или и то, и другое:
locale: | cs_CZ | en_US |
---|---|---|
date: short |
23.01.78 | 1/23/78 |
date: medium |
23. 1. 1978 | Jan 23, 1978 |
date: long |
23. ledna 1978 | January 23, 1978 |
date: full |
pondělí 23. ledna 1978 | Monday, January 23, 1978 |
time: short |
8:30 | 8:30 AM |
time: medium |
8:30:59 | 8:30:59 AM |
time: long |
8:30:59 SEČ | 8:30:59 AM GMT+1 |
date: short, time: short |
23.01.78 8:30 | 1/23/78, 8:30 AM |
date: medium, time: short |
23. 1. 1978 8:30 | Jan 23, 1978, 8:30 AM |
date: long, time: short |
23. ledna 1978 v 8:30 | January 23, 1978 at 8:30 AM |
Для даты также можно использовать префикс 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&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' *}
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 *}
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
для строк с резервным вариантом на функцию 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}
Вы также можете определить callback-функцию, которая определит значение, по которому нужно сортировать:
{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 < 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>
<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 = 'Náš 10. produkt'}
{$s|webalize} {* выводит 'nas-10-produkt' *}
Требуется библиотека nette/utils.