Фильтры для 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}
Также существует как 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' *}
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 регистр.
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}
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&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} {* выходы '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 *}
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 < 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.