Фильтры 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|localDate: format: yM}      {* 4/2024 *}
{$date|localDate: date: medium}    {* 15. 4. 2024 *}

Если вы используете фильтр без параметров, дата будет выведена на уровне long, см. далее.

a) использование формата

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

Порядок кодов в формате не имеет значения, так как порядок компонентов выводится в соответствии с обычаями локали. Таким образом, формат не зависит от нее. Например, формат yyyyMMMMd в среде en_US выведет April 15, 2024, тогда как в среде ru_RU выведет 15 апреля 2024:

б) использование предустановленных стилей

Параметры 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 для строк с резервным вариантом на функцию 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 &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-produkt' *}

Требуется библиотека nette/utils.