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

См. также метки group и iterateWhile.

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-функцией date. Фильтр принимает дату в формате временной метки UNIX, как строку или как объект 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:','}    {* 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 регистр.

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, строки или объекта DateTimeInterface.

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

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

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

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

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

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

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

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

{$date|localDate: date: relative-short}    {* yesterday *}

См. также дата.

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

number (string $format)

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

• <c id=6/> обязательная цифра, отображается всегда, даже если она равна нулю
• # необязательная цифра, отображается только в том случае, если число имеет цифру на этом месте
• @ значащая цифра, помогает отобразить число с определенным количеством значащих цифр
• . обозначает место, где должен находиться десятичный разделитель (запятая или точка, в зависимости от локали)
• , используется для разделения групп цифр, обычно тысяч
• % умножает число на 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'}  {* 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 (?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' в примере указывает, что сортировка будет производиться по $row->name или $row['name']в зависимости от того, является ли $row массивом или объектом:

{foreach ($items|sort: by: 'name') as $item}
	{$item->name}
{/foreach}

Вы также можете определить функцию обратного вызова, которая определяет значение для сортировки:

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

Извлекает фрагмент строки. Этот фильтр был заменен фильтром срезов.

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