Фильтры для 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>

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}

Также существует как clamp.

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}    {* выходы 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 регистр.

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}

lower

Преобразует значение в нижний регистр. Требуется расширение PHP mbstring.

{='LATTE'|lower}   {* выходы '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'}  {* выходы '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}  {* выходы '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}    {* returns ['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'] *}

Фильтр срезов работает как функция array_slice PHP для массивов и mb_substr для строк с возвратом к iconv_substr в режиме UTF-8.

Если start неотрицательно, то последовательность начнется с этого начала в переменной. Если start отрицательно, то последовательность начнется на таком-то расстоянии от конца переменной.

Если задана длина и она положительна, то последовательность будет содержать до этого количества элементов. Если переменная короче длины, то будут присутствовать только доступные элементы переменной. Если длина задана и отрицательна, то последовательность остановится на столько элементов от конца переменной. Если длина не указана, то последовательность будет содержать все элементы от смещения до конца переменной.

Filter по умолчанию переупорядочивает и сбрасывает ключи целочисленного массива. Это поведение можно изменить, установив 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 &lt; two</p>'|stripHtml}  {* выходы '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}    {* выходы '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}  {* outputs 'LATTE' *}

См. также capitalize, firstUpper, lower.

webalize

Преобразование в ASCII.

Преобразует пробелы в дефисы. Удаляет символы, не являющиеся алфавитно-цифровыми, подчеркиванием или дефисом. Преобразует в строчные буквы. Также удаляет ведущие и последующие пробельные символы.

{var $s = 'Our 10. product'}
{$s|webalize}    {* выходы 'our-10-product' *}

Требуется пакет nette/utils.