Filtros Latte

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

Transformação
batch exibição de dados lineares em uma tabela
breakLines Adiciona quebras de linha HTML antes do final da linha
bytes formata o tamanho em bytes
clamp limita o valor ao intervalo especificado
dataStream conversão para o protocolo Data URI
date formata data e hora
explode divide uma string em um array por um separador
first retorna o primeiro elemento de um array ou caractere de uma string
group agrupa dados por vários critérios
implode une um array em uma string
indent indenta o texto da esquerda por um número especificado de tabulações
join une um array em uma string
last retorna o último elemento de um array ou caractere de uma string
length retorna o comprimento de uma string em caracteres ou de um array
localDate formata data e hora de acordo com a localidade
number formata um número
padLeft preenche uma string à esquerda até o comprimento desejado
padRight preenche uma string à direita até o comprimento desejado
random retorna um elemento aleatório de um array ou caractere de uma string
repeat repetição de string
replace substitui ocorrências da string de pesquisa
replaceRE substitui ocorrências de acordo com uma expressão regular
reverse inverte uma string UTF-8 ou um array
slice extrai uma parte de um array ou string
sort ordena um array
spaceless remove espaços em branco, semelhante à tag spaceless
split divide uma string em um array por um separador
strip remove espaços em branco
stripHtml remove tags HTML e converte entidades HTML em caracteres
substr retorna uma parte de uma string
trim remove espaços em branco ou outros caracteres do início e do fim
translate tradução para outros idiomas
truncate reduz o comprimento preservando palavras
webalize modifica uma string UTF-8 para a forma usada em URLs
Capitalização
capitalize minúsculas, primeira letra das palavras maiúscula
firstUpper converte a primeira letra para maiúscula
lower converte para minúsculas
upper converte para maiúsculas
Arredondamento
ceil arredonda um número para cima para a precisão dada
floor arredonda um número para baixo para a precisão dada
round arredonda um número para a precisão dada
Escaping
escapeUrl escapa um parâmetro em uma URL
noescape imprime uma variável sem escapar
query gera uma query string em uma URL

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 você não precisa escrevê-los.

Segurança
checkUrl trata um endereço URL contra entradas perigosas
nocheck evita o tratamento automático do endereço URL

Os atributos Latte src e href verificam automaticamente, então você quase nunca precisa 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 registrados desta forma:

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

No template, ele é 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 você fornecer um segundo parâmetro, ele será usado para preencher os itens ausentes 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.

Tenhamos 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 em uma URL.

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

Veja também query.

explode (string $separator='')

Divide uma string em um 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'] *}

Você 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' *}

Você 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|format: yM}                 {* 4/2024 *}
{$date|localDate: date: medium}    {* 15/04/2024 *}

Se você 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:

ano y / yy / yyyy 2024 / 24 / 2024
mês M / MM / MMMMMMM 8 / 08 / agoagosto
dia d / dd / EEEEE 1 / 01 / domdomingo
hora j / H / h preferido / 24 horas / 12 horas
minuto m / mm 5 / 05 (2 dígitos em combinação com segundos)
segundo s / ss 8 / 08 (2 dígitos em combinação com minutos)

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 cs_CZ exibe 15. dubna 2024:

locale: cs_CZ en_US
format: 'dMy' 10. 8. 2024 8/10/2024
format: 'yM' 8/2024 8/2024
format: 'yyyyMMMM' srpen 2024 August 2024
format: 'MMMM' srpen August
format: 'jm' 17:22 5:22 PM
format: 'Hm' 17:22 17:22
format: 'hm' 5:22 odp. 5:22 PM

b) uso de estilos predefinidos

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

locale: cs_CZ en_US
date: short 23.01.78 1/23/78
date: medium 23. 1. 1978 Jan 23, 1978
date: long 23. ledna 1978 January 23, 1978
date: full pondělí 23. ledna 1978 Monday, January 23, 1978
time: short 8:30 8:30 AM
time: medium 8:30:59 8:30:59 AM
time: long 8:30:59 SEČ 8:30:59 AM GMT+1
date: short, time: short 23.01.78 8:30 1/23/78, 8:30 AM
date: medium, time: short 23. 1. 1978 8:30 Jan 23, 1978, 8:30 AM
date: long, time: short 23. ledna 1978 v 8:30 January 23, 1978 at 8:30 AM

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 você 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>hello</b>'}
Escapado: {$trustedHtmlString}
Não escapado: {$trustedHtmlString|noescape}

Exibe:

Escapado: &lt;b&gt;hello&lt;/b&gt;
Não escapado: <b>hello</b>

O uso incorreto do filtro noescape pode levar à vulnerabilidade XSS! Nunca o use a menos que tenha certeza absoluta do que está fazendo 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 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 você não precisa 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 em uma 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 menor em length elementos a partir 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 suas chaves associativas. Quando a localidade está definida, a ordenação segue 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}

Você 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 você precisar 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}

Você 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. Você 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 texto.

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

O texto puro resultante pode naturalmente conter caracteres que representam tags HTML, por exemplo, '&lt;p&gt;'|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. Você 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.

versão: 3.0