Filtros Latte

Nos templates, podemos usar funções que ajudam a modificar ou reformatar dados para a forma final. Chamamo-las de filtros.

Além disso, existem filtros de escaping para HTML (escapeHtml e escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) e iCalendar (escapeICal), que o Latte usa por si só graças ao escaping sensível ao contexto e não é necessário escrevê-los.

Os atributos Latte src e href verificam automaticamente, pelo que quase nunca precisa de usar o filtro checkUrl.

Todos os filtros padrão são destinados a strings na codificação UTF-8.

Uso

Os filtros são escritos após uma barra vertical (pode haver um espaço antes dela):

<h1>{$heading|upper}</h1>

Os filtros (em versões mais antigas, helpers) podem ser encadeados e são aplicados na ordem da esquerda para a direita:

<h1>{$heading|lower|capitalize}</h1>

Os parâmetros são inseridos após o nome do filtro, separados por dois pontos ou vírgulas:

<h1>{$heading|truncate:20,''}</h1>

Os filtros também podem ser aplicados a uma expressão:

{var $name = ($title|upper) . ($subtitle|lower)}</h1>

Filtros personalizados podem ser registados desta forma:

$latte = new Latte\Engine;
$latte->addFilter('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));

No template, é chamado assim:

<p>{$text|shortify}</p>
<p>{$text|shortify:100}</p>

Filtros

batch (int $length, mixed $item): array

Filtro que simplifica a exibição de dados lineares na forma de uma tabela. Retorna um array de arrays com o número especificado de itens. Se fornecer um segundo parâmetro, ele será usado para preencher os itens em falta na última linha.

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

Exibe:

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

Veja também group e a tag iterateWhile.

breakLines

Adiciona a tag HTML <br> antes de cada caractere de nova linha.

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* exibe "Text &amp; with <br>\n newline" *}

bytes (int $precision=2)

Formata o tamanho em bytes de forma legível por humanos. Se a localidade estiver definida, os separadores decimais e de milhares correspondentes serão usados.

{$size|bytes}     0 B, 1.25 GB, …
{$size|bytes:0}   10 B, 1 GB, …

ceil (int $precision=0)

Arredonda um número para cima para a precisão dada.

{=3.4|ceil}         {* exibe 4      *}
{=135.22|ceil:1}    {* exibe 135.3  *}
{=135.22|ceil:3}    {* exibe 135.22 *}

Veja também floor, round.

capitalize

As palavras começarão com letras maiúsculas, todos os caracteres restantes serão minúsculos. Requer a extensão PHP mbstring.

{='i like LATTE'|capitalize}  {* exibe 'I Like Latte' *}

Veja também firstUpper, lower, upper.

checkUrl

Força o tratamento do endereço URL. Verifica se a variável contém uma URL da web (ou seja, protocolo HTTP/HTTPS) e evita a exibição de links que podem representar um risco de segurança.

{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>verificado</a>
<a data-href={$link}>não verificado</a>

Exibe:

<a data-href="">verificado</a>
<a data-href="javascript:window.close()">não verificado</a>

Veja também nocheck.

clamp (int|float $min, int|float $max)

Limita o valor ao intervalo inclusivo especificado de min e max.

{$level|clamp: 0, 255}

Existe também como função.

dataStream (string $mimetype=detect)

Converte o conteúdo para o esquema data URI. Com ele, é possível incorporar imagens em HTML ou CSS sem a necessidade de vincular arquivos externos.

Tenha na variável a imagem $img = Image::fromFile('imagem.gif'), então

<img src={$img|dataStream}>

Exibe, por exemplo:

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

Requer a extensão PHP fileinfo.

date (string $format)

Formata data e hora de acordo com a máscara usada pela função PHP date. O filtro aceita a data no formato timestamp UNIX, como string ou objeto do tipo DateTimeInterface.

{$today|date:'j. n. Y'}

Veja também localDate.

escapeUrl

Escapa uma variável para uso como parâmetro numa URL.

<a href="http://example.com/{$name|escapeUrl}">{$name}</a>

Veja também query.

explode (string $separator='')

Divide uma string num array por um separador. Alias para split.

{='one,two,three'|explode:','}    {* retorna ['one', 'two', 'three'] *}

Se o separador for uma string vazia (valor padrão), a entrada será dividida em caracteres individuais:

{='123'|explode}                  {* retorna ['1', '2', '3'] *}

Também pode usar o alias split:

{='1,2,3'|split:','}              {* retorna ['1', '2', '3'] *}

Veja também implode.

first

Retorna o primeiro elemento de um array ou caractere de uma string:

{=[1, 2, 3, 4]|first}    {* exibe 1 *}
{='abcd'|first}          {* exibe 'a' *}

Veja também last, random.

floor (int $precision=0)

Arredonda um número para baixo para a precisão dada.

{=3.5|floor}        {* exibe 3      *}
{=135.79|floor:1}   {* exibe 135.7  *}
{=135.79|floor:3}   {* exibe 135.79 *}

Veja também ceil, round.

firstUpper

Converte a primeira letra para maiúscula. Requer a extensão PHP mbstring.

{='the latte'|firstUpper}  {* exibe 'The latte' *}

Veja também capitalize, lower, upper.

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

O filtro agrupa dados por vários critérios.

Neste exemplo, as linhas da tabela são agrupadas pela coluna categoryId. A saída é um array de arrays, onde a chave é o valor na coluna categoryId. Leia o tutorial detalhado.

{foreach ($items|group: categoryId) as $categoryId => $categoryItems}
    <ul>
        {foreach $categoryItems as $item}
            <li>{$item->name}</li>
        {/foreach}
    </ul>
{/foreach}

Veja também batch, a função group e a tag iterateWhile.

implode (string $glue='')

Retorna uma string que é a concatenação dos itens da sequência. Alias para join.

{=[1, 2, 3]|implode}      {* exibe '123' *}
{=[1, 2, 3]|implode:'|'}  {* exibe '1|2|3' *}

Também pode usar o alias join:

{=[1, 2, 3]|join}         {* exibe '123' *}

indent (int $level=1, string $char="\t")

Indenta o texto da esquerda por um número especificado de tabulações ou outros caracteres, que podem ser especificados no segundo argumento. Linhas vazias não são indentadas.

<div>
{block |indent}
<p>Hello</p>
{/block}
</div>

Exibe:

<div>
	<p>Hello</p>
</div>

last

Retorna o último elemento de um array ou caractere de uma string:

{=[1, 2, 3, 4]|last}    {* exibe 4 *}
{='abcd'|last}          {* exibe 'd' *}

Veja também first, random.

length

Retorna o comprimento de uma string ou array.

• para strings, retorna o comprimento em caracteres UTF-8
• para arrays, retorna o número de itens
• para objetos que implementam a interface Countable, usa o valor de retorno do método count()
• para objetos que implementam a interface IteratorAggregate, usa o valor de retorno da função iterator_count()

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

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

Formata data e hora de acordo com a localidade, o que garante uma exibição consistente e localizada de informações de tempo em diferentes idiomas e regiões. O filtro aceita a data como timestamp UNIX, string ou objeto do tipo DateTimeInterface.

{$date|localDate}                  {* 15 de abril de 2024 *}
{$date|localDate: format: yM}      {* 4/2024 *}
{$date|localDate: date: medium}    {* 15/04/2024 *}

Se usar o filtro sem parâmetros, a data será exibida no nível long, veja abaixo.

a) uso do formato

O parâmetro format descreve quais componentes de tempo devem ser exibidos. Ele usa códigos de letras para eles, cujo número de repetições afeta a largura da saída:

A ordem dos códigos no formato não importa, pois a ordem dos componentes será exibida de acordo com os costumes da localidade. O formato é, portanto, independente dela. Por exemplo, o formato yyyyMMMMd no ambiente en_US exibe April 15, 2024, enquanto no ambiente pt_BR exibe 15 de abril de 2024:

b) uso de estilos predefinidos

Os parâmetros date e time determinam com que detalhe a data e a hora devem ser exibidas. Pode escolher entre vários níveis: full, long, medium, short. É possível exibir apenas a data, apenas a hora ou ambos:

Para a data, também pode ser usado o prefixo relative- (por exemplo, relative-short), que para datas próximas ao presente exibirá ontem, hoje ou amanhã, caso contrário, será exibido da maneira padrão.

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

Veja também date.

lower

Converte uma string para minúsculas. Requer a extensão PHP mbstring.

{='LATTE'|lower}   {* exibe 'latte' *}

Veja também capitalize, firstUpper, upper.

nocheck

Evita o tratamento automático do endereço URL. O Latte verifica automaticamente se a variável contém uma URL da web (ou seja, protocolo HTTP/HTTPS) e evita a exibição de links que podem representar um risco de segurança.

Se o link usar outro esquema, como javascript: ou data:, e tiver certeza do seu conteúdo, pode desativar a verificação usando |nocheck.

{var $link = 'javascript:window.close()'}

<a href={$link}>verificado</a>
<a href={$link|nocheck}>não verificado</a>

Exibe:

<a href="">verificado</a>
<a href="javascript:window.close()">não verificado</a>

Veja também checkUrl.

noescape

Desativa o escaping automático.

{var $trustedHtmlString = '<b>olá</b>'}
Escapado: {$trustedHtmlString}
Não escapado: {$trustedHtmlString|noescape}

Exibe:

Escapado: <b>olá</b>
Não escapado: <b>olá</b>

O uso incorreto do filtro noescape pode levar à vulnerabilidade XSS! Nunca o use a menos que tenha certeza absoluta do que está a fazer e que a string exibida vem de uma fonte confiável.

number (int $decimals=0, string $decPoint='.', string $thousandsSep=',')

Formata um número para um certo número de casas decimais. Se a localidade estiver definida, os separadores decimais e de milhares correspondentes serão usados.

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

O parâmetro format permite definir a aparência dos números exatamente de acordo com as suas necessidades. Para isso, é necessário ter a localidade configurada. O formato consiste em vários caracteres especiais, cuja descrição completa pode ser encontrada na documentação DecimalFormat:

• 0 dígito obrigatório, sempre será exibido, mesmo que seja zero
• # dígito opcional, será exibido apenas se o número realmente existir neste local
• @ dígito significativo, ajuda a exibir o número com um certo número de dígitos válidos
• . indica onde deve estar a vírgula decimal (ou ponto, dependendo do país)
• , serve para separar grupos de dígitos, mais comumente milhares
• % multiplica o número por 100× e adiciona o sinal de porcentagem

Vamos dar uma olhada nos exemplos. No primeiro exemplo, duas casas decimais são obrigatórias, no segundo, opcionais. O terceiro exemplo mostra o preenchimento com zeros à esquerda e à direita, o quarto exibe apenas os dígitos existentes:

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

Os dígitos significativos determinam quantos dígitos, independentemente da vírgula decimal, devem ser exibidos, com arredondamento:

{1234|number: '@@'}             {* 1200 *}
{1234|number: '@@@'}            {* 1230 *}
{1234|number: '@@@#'}           {* 1234 *}
{1.2345|number: '@@@'}          {* 1.23 *}
{0.00123|number: '@@'}          {* 0.0012 *}

Uma maneira fácil de exibir um número como porcentagem. O número é multiplicado por 100× e o sinal % é adicionado:

{0.1234|number: '#.##%'}        {* 12.34% *}

Podemos definir um formato diferente para números positivos e negativos, separados pelo caractere ;. Desta forma, por exemplo, pode-se definir que números positivos devem ser exibidos com o sinal +:

{42|number: '#.##;(#.##)'}      {* 42 *}
{-42|number: '#.##;(#.##)'}     {* (42) *}
{42|number: '+#.##;-#.##'}      {* +42 *}
{-42|number: '+#.##;-#.##'}     {* -42 *}

Lembre-se de que a aparência real dos números pode variar dependendo das configurações do país. Por exemplo, em alguns países, usa-se vírgula em vez de ponto como separador decimal. Este filtro leva isso em consideração automaticamente e não precisa de se preocupar com nada.

padLeft (int $length, string $pad=' ')

Preenche uma string até um certo comprimento com outra string pela esquerda.

{='hello'|padLeft: 10, '123'}  {* exibe '12312hello' *}

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

Preenche uma string até um certo comprimento com outra string pela direita.

{='hello'|padRight: 10, '123'}  {* exibe 'hello12312' *}

query

Gera dinamicamente uma query string numa URL:

<a href="http://example.com/?{[name: 'John Doe', age: 43]|query}">clique</a>
<a href="http://example.com/?search={$search|query}">pesquisar</a>

Exibe:

<a href="http://example.com/?name=John+Doe&amp;age=43">clique</a>
<a href="http://example.com/?search=Foo+Bar">pesquisar</a>

Chaves com valor null são omitidas.

Veja também escapeUrl.

random

Retorna um elemento aleatório de um array ou caractere de uma string:

{=[1, 2, 3, 4]|random}    {* exibe por ex.: 3 *}
{='abcd'|random}          {* exibe por ex.: 'b' *}

Veja também first, last.

repeat (int $count)

Repete uma string x vezes.

{='hello'|repeat: 3}  {* exibe 'hellohellohello' *}

replace (string|array $search, string $replace='')

Substitui todas as ocorrências da string de pesquisa pela string de substituição.

{='hello world'|replace: 'world', 'friend'}  {* exibe 'hello friend' *}

É possível realizar várias substituições de uma vez:

{='hello world'|replace: [h => l, l => h]}  {* exibe 'lehho worhd' *}

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

Realiza uma pesquisa de expressão regular com substituição.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* exibe 'hel' *}

reverse

Inverte a string ou array fornecido.

{var $s = 'Nette'}
{$s|reverse}    {* exibe 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* retorna ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

Arredonda um número para a precisão dada.

{=3.4|round}        {* exibe 3      *}
{=3.5|round}        {* exibe 4      *}
{=135.79|round:1}   {* exibe 135.8  *}
{=135.79|round:3}   {* exibe 135.79 *}

Veja também ceil, floor.

slice (int $start, ?int $length=null, bool $preserveKeys=false)

Extrai uma parte de um array ou string.

{='hello'|slice: 1, 2}           {* exibe 'el' *}
{=['a', 'b', 'c']|slice: 1, 2}   {* exibe ['b', 'c'] *}

O filtro funciona como a função PHP array_slice para arrays ou mb_substr para strings com fallback para a função iconv_substr no modo UTF-8.

Se start for positivo, a sequência começará deslocada por este número a partir do início do array/string. Se for negativo, a sequência começará deslocada por tanto a partir do fim.

Se o parâmetro length for especificado e for positivo, a sequência conterá tantos elementos. Se um parâmetro length negativo for passado para esta função, a sequência conterá todos os elementos do array original, começando na posição start e terminando na posição length elementos antes do fim do array. Se este parâmetro não for especificado, a sequência conterá todos os elementos do array original, começando na posição start.

Por padrão, o filtro reordena e redefine as chaves inteiras do array. Este comportamento pode ser alterado definindo preserveKeys como true. As chaves de string são sempre preservadas, independentemente deste parâmetro.

sort (?Closure $comparison, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false)

O filtro ordena os elementos de um array ou iterador e preserva as suas chaves associativas. Quando a localidade está definida, a ordenação segue as suas regras, a menos que uma função de comparação personalizada seja especificada.

{foreach ($names|sort) as $name}
	...
{/foreach}

Array ordenado em ordem inversa:

{foreach ($names|sort|reverse) as $name}
	...
{/foreach}

Pode especificar uma função de comparação personalizada para ordenação (o exemplo mostra como inverter a ordenação do maior para o menor):

{var $reverted = ($names|sort: fn($a, $b) => $b <=> $a)}

O filtro |sort também permite ordenar elementos por chaves:

{foreach ($names|sort: byKey: true) as $name}
	...
{/foreach}

Se precisar de ordenar uma tabela por uma coluna específica, pode usar o parâmetro by. O valor 'name' no exemplo especifica que a ordenação será por $item->name ou $item['name'], dependendo se $item é um array ou objeto:

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

Também pode definir uma função de callback que determinará o valor pelo qual ordenar:

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

O parâmetro byKey pode ser usado da mesma maneira.

spaceless

Remove espaços em branco desnecessários da saída. Também pode usar o alias strip.

{block |spaceless}
	<ul>
		<li>Hello</li>
	</ul>
{/block}

Exibe:

<ul> <li>Hello</li> </ul>

stripHtml

Converte HTML para texto puro. Ou seja, remove as tags HTML e converte as entidades HTML em caracteres.

{='<p>one &lt; two</p>'|stripHtml}  {* exibe 'one < two' *}

O texto puro resultante pode naturalmente conter caracteres que representam tags HTML, por exemplo, '<p>'|stripHtml é convertido para <p>. Em nenhuma circunstância exiba o texto resultante com |noescape, pois isso pode levar a uma falha de segurança.

substr (int $offset, ?int $length=null)

Extrai uma parte de uma string. Este filtro foi substituído pelo filtro slice.

{$string|substr: 1, 2}

translate (…$args)

Traduz expressões para outros idiomas. Para que o filtro esteja disponível, é necessário configurar o tradutor. Também pode usar tags para tradução.

<a href="basket">{='Carrinho'|translate}</a>
<span>{$item|translate}</span>

trim (string $charlist=" \t\n\r\0\x0B\u{A0}")

Remove espaços em branco (ou outros caracteres) do início e do fim de uma string.

{='  I like Latte.  '|trim}    {* exibe 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* exibe '  I like Latte' *}

truncate (int $length, string $append='…')

Corta uma string para o comprimento máximo especificado, tentando preservar palavras inteiras. Se a string for encurtada, adiciona reticências no final (pode ser alterado com o segundo parâmetro).

{var $title = 'Hello, how are you?'}
{$title|truncate:5}  {* Hell…                *}
{$title|truncate:17} {* Hello, how are…      *}
{$title|truncate:30} {* Hello, how are you?  *}

upper

Converte uma string para maiúsculas. Requer a extensão PHP mbstring.

{='latte'|upper}  {* exibe 'LATTE' *}

Veja também capitalize, firstUpper, lower.

webalize

Modifica uma string UTF-8 para a forma usada em URLs.

Converte para ASCII. Converte espaços em hífens. Remove caracteres que não são alfanuméricos, sublinhados ou hífens. Converte para minúsculas. Também remove espaços iniciais e finais.

{var $s = 'Nosso 10º produto'}
{$s|webalize}   {* exibe 'nosso-10-produto' *}

Requer a biblioteca nette/utils.