Фильтры 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)}

Пользовательские фильтры можно зарегистрировать так:

$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>

Nullsafe-фильтры

Любой фильтр можно сделать nullsafe, использовав ?| вместо |. Если значение равно null, фильтр не выполняется и возвращается null. Последующие фильтры цепочки тоже пропускаются.

Это полезно в сочетании с HTML-атрибутами, которые опускаются, если значение равно null.

<div title={$title?|upper}>
{* Если $title равно null: <div> *}
{* Если $title равно 'hello': <div title="HELLO"> *}

Фильтры

accept

Фильтр используется при миграции с Latte 3.0, чтобы подтвердить, что вы проверили изменение поведения атрибута и принимаете его. Значение он не изменяет.

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

batch (int $length, mixed $rest=null): Generator

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

{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' *}

См. также firstLower, firstUpper, lower, upper.

checkUrl

Принудительно очищает URL. Он проверяет, использует ли URL безопасную схему (http, https, ftp, mailto, tel, sms) или является относительной ссылкой, и блокирует опасные схемы вроде javascript:, которые могли бы создать угрозу безопасности.

{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}

Существует также как функция.

column (string|int|null $columnKey, string|int|null $indexKey=null)

Возвращает значения одного столбца $columnKey из многомерного массива в виде нового массива. Может применяться и к массивам объектов для извлечения значений свойств.

{var $users = [
	[id: 30, name: 'John', age: 30],
	[id: 32, name: 'Jane', age: 25],
	[id: 33, age: 35],
]}

{$users|column: 'name'}
{* возвращает ['John', 'Jane'] *}

{$users|column: 'name', 'id'}
{* возвращает [30 => 'John', 32 => 'Jane'] *}

Если вы передадите null как ключ столбца, массив будет переиндексирован по $indexKey.

commas (?string $lastGlue=null)

Объединяет элементы массива запятой с пробелом (', '). Удобное сокращение для перечисления элементов в удобочитаемом виде.

{var $items = ['apples', 'oranges', 'bananas']}
{$items|commas}
{* выводит 'apples, oranges, bananas' *}

Вы можете также задать собственный разделитель для последней пары элементов:

{$items|commas: ' and '}
{* выводит 'apples, oranges and bananas' *}

{=['PHP', 'JavaScript', 'Python']|commas: ', or '}
{* выводит 'PHP, JavaScript, or Python' *}

См. также implode.

dataStream (?string $type=null)

Преобразует содержимое в схему data URI. Это позволяет встраивать изображения в HTML или CSS без ссылок на внешние файлы. Если $type равно null, MIME-тип определяется автоматически.

Пусть в переменной находится изображение $img = Image::fromFile('image.gif'), тогда

<img src={$img|dataStream}>

Выводит, например:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
9TXL0Y4OHwAAAABJRU5ErkJggg==">

Требует расширение PHP fileinfo.

date (string $format='j. n. Y')

Форматирует дату и время по маске, используемой функцией PHP date. Фильтр принимает дату как UNIX-время, строку, объект DateTimeInterface или DateInterval.

{$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.

filter (callable $predicate): iterable

Отбирает элементы массива или итератора, оставляя только те, для которых предикат возвращает true. Ключи сохраняются.

{foreach ($people|filter: fn($person) => $person->age >= 18) as $adult}
	<p>{$adult->name}</p>
{/foreach}

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.

firstLower

Переводит первую букву в нижний регистр. Требует расширение PHP mbstring.

{='The Latte'|firstLower}  {* выводит 'the Latte' *}

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

firstUpper

Переводит первую букву в верхний регистр. Требует расширение PHP mbstring.

{='the latte'|firstUpper}  {* выводит 'The latte' *}

См. также capitalize, firstLower, lower, upper.

group (string|int|\Closure $by): iterable

Фильтр группирует данные по разным критериям.

В этом примере записи таблицы группируются по столбцу 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' *}

См. также commas, explode.

indent (int $level=1, string $chars="\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()
• для объектов, реализующих интерфейс Traversable, использует возвращаемое значение функции iterator_count()

{if ($users|length) > 10}
	...
{/if}

localDate (?string $format=null, ?string $date=null, ?string $time=null)

Форматирует дату и время по локали, обеспечивая единообразное и локализованное отображение временных данных в разных языках и регионах. Фильтр принимает дату как UNIX-время, строку или объект DateTimeInterface.

{$date|localDate}                  {* 15. dubna 2024 *}
{$date|localDate: format: yM}      {* 4/2024 *}
{$date|localDate: date: medium}    {* 15. 4. 2024 *}

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

a) Использование format

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

Порядок кодов в формате не важен, потому что порядок составляющих определяется правилами локали. Таким образом, формат не зависит от локали. Например, формат yyyyMMMMd в локали en_US выводит April 15, 2024, а в локали cs_CZ – 15. dubna 2024:

b) Использование готовых стилей

Параметры date и time определяют, насколько подробно должны отображаться дата и время. Вы можете выбрать из нескольких уровней: full, long, medium, short. Можно отображать только дату, только время или и то, и другое:

Для даты можно также использовать префикс relative- (например, relative-short), который для дат, близких к сегодняшнему дню, выведет вчера, сегодня или завтра, а в остальных случаях выведет дату обычным способом.

{$date|localDate: date: relative-short}    {* вчера *}

См. также date.

lower

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

{='LATTE'|lower}   {* выводит 'latte' *}

См. также capitalize, firstLower, firstUpper, upper.

map (callable $transformer): iterable

Преобразует каждый элемент массива или итератора с помощью callback и возвращает новый итератор. Это противоположность фильтра filter. Ключи сохраняются.

{=($users|map: fn($user) => $user->name)|implode: ', '}   {* John, Mary, Paul *}

См. также filter.

nocheck

Предотвращает автоматическую очистку URL. Latte проверяет автоматически, использует ли URL безопасную схему (такую как http, https, ftp, mailto, tel, sms) или является относительной ссылкой, и блокирует потенциально опасные.

Если ссылка использует другую схему, например 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 *}

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 $append=' ')

Дополняет строку или число до определённой длины другой строкой слева.

{='hello'|padLeft: 10, '123'}  {* выводит '12312hello' *}
{=123|padLeft: 5, '0'}         {* выводит '00123' *}

padRight (int $length, string $append=' ')

Дополняет строку или число до определённой длины другой строкой справа.

{='hello'|padRight: 10, '123'}  {* выводит 'hello12312' *}
{=123|padRight: 5, '0'}         {* выводит '12300' *}

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|array $replace='')

Заменяет все вхождения искомой строки строкой замены.

{='hello world'|replace: 'world', 'friend'}  {* выводит 'hello friend' *}

Несколько замен можно сделать сразу:

{='hello world'|replace: [h => l, l => h]}  {* выводит 'lehho worhd' *}

replaceRE (string $pattern, string $replacement='')

Выполняет поиск и замену по регулярному выражению.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* выводит 'hel' *}

reverse (bool $preserveKeys=false)

Переворачивает заданную строку или массив.

{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 для строк. Для итераторов он возвращает генератор: элементы забираются из источника по одному, и чтение прекращается, как только достигнут предел. Итератор целиком в память никогда не загружается.

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

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

По умолчанию фильтр переупорядочивает и сбрасывает целочисленные ключи массива. Это поведение можно изменить, установив preserveKeys в true. Строковые ключи сохраняются всегда, независимо от этого параметра.

См. также limit.

limit (int $length)

Ограничивает длину массива, строки или итератора. Для массивов и итераторов ключи сохраняются. Для строк учитывается UTF-8.

{foreach ($items|limit: 5) as $item}
	...
{/foreach}

{$text|limit: 100}

sort (?Closure $comparison=null, 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($item) => $item->category->name) as $item}
	{$item->name}
{/foreach}

Параметр byKey используется точно так же.

spaceless

Убирает из вывода лишние пробельные символы. Можно использовать и устаревший псевдоним strip, но предпочтительнее spaceless.

{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 $start, ?int $length=null)

Извлекает часть строки. Этот фильтр заменён фильтром slice.

{$string|substr: 1, 2}

toggle

Фильтр toggle управляет наличием атрибута по логическому значению. Если значение истинно, атрибут присутствует; если ложно, атрибут полностью опускается:

<div uk-grid={$isGrid|toggle}>
{* Если $isGrid истинно: <div uk-grid> *}
{* Если $isGrid ложно: <div> *}

Этот фильтр полезен для собственных атрибутов или атрибутов JavaScript-библиотек, которым нужно управление наличием и отсутствием, похожее на логические HTML-атрибуты.

Фильтр можно использовать только внутри HTML-атрибутов.

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, firstLower, firstUpper, lower.

webalize

Приводит строку UTF‑8 к формату, используемому в URL.

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

{var $s = 'Our 10th product'}
{$s|webalize}   {* выводит 'our-10th-product' *}

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