Filtros de Latte

Os filtros são funções que mudam ou formatam os dados para um formulário que desejamos. Este é um resumo dos filtros incorporados que estão disponíveis.

Há também filtros de fuga para HTML (escapeHtml e escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) e iCalendar (escapeICal), que Latte se utiliza graças à fuga consciente do contexto e você não precisa escrevê-los.

Latte os atributos src e href verificam automaticamente, de modo que quase não é necessário usar o filtro checkUrl.

Todos os filtros integrados trabalham com cordas codificadas UTF-8.

Utilização

O Latte permite a chamada de filtros utilizando a notação do sinal de canalização (o espaço precedente é permitido):

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

Os filtros podem ser acorrentados, nesse caso, eles se aplicam por ordem da esquerda para a direita:

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

Os parâmetros são colocados após o nome do filtro separado por dois pontos ou vírgula:

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

Os filtros podem ser aplicados por expressão:

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

Os 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));

Usamo-lo em um modelo como este:

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

Filtros

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

Filtro que simplifica a listagem de dados lineares na forma de uma tabela. Ele retorna uma matriz com o determinado número de itens. Se você fornecer um segundo parâmetro, este é 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>

Impressões:

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

Consulte também a tag group e iterateWhile.

breakLines

Insere quebras de linha HTML antes de todas as novas linhas.

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

bytes (int $precision=2)

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

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

ceil (int $precision=0)

Arredonda um número até uma determinada precisão.

{=3.4|ceil}         {* saídas 4 *}
{=135.22|ceil:1}    {* saídas 135,3 *}
{=135.22|ceil:3}    {* saídas 135,22 *}

Veja também piso, redondo.

capitalize

Devolve uma versão do valor com base no título. As palavras começarão com letras maiúsculas, todos os caracteres restantes são minúsculos. Requer extensão PHP mbstring.

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

Ver também firstUpper, lower, upper.

checkUrl

Impõe a higienização do URL. Verifica se a variável contém uma URL da web (ou seja, protocolo HTTP/HTTPS) e impede a escrita de links que possam representar um risco de segurança.

{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>checked</a>
<a data-href={$link}>unchecked</a>

Impressões:

<a data-href="">checked</a>
<a data-href="javascript:window.close()">unchecked</a>

Veja também nocheck.

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

Retorna o valor fixado para a faixa inclusiva de min e max.

{$level|clamp: 0, 255}

Também existe como função.

dataStream (string $mimetype=detect)

Converte o conteúdo para o esquema URI de dados. Pode ser usado para inserir imagens em HTML ou CSS sem a necessidade de vincular arquivos externos.

Vamos ter uma imagem em uma variável $img = Image::fromFile('obrazek.gif'), então

<img src={$img|dataStream}>

Impressões, por exemplo:

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

Requer extensão PHP fileinfo.

date (string $format)

Formata a data e a hora de acordo com a máscara usada pela função PHP date. O filtro aceita a data no formato de carimbo de data/hora do UNIX, como uma cadeia de caracteres ou como um objeto DateTimeInterface.

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

Consulte também localDate.

escapeUrl

Escapa a uma variável para ser usada como parâmetro na URL.

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

Veja também consulta.

explode (string $separator='')

Divide um fio pelo delimitador dado e retorna um conjunto de fios. Alias para split.

{='um,dois,três'|explodir:','}    {* retorna ['um', 'dois', 'três'] *}

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

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

Você também pode usar o pseudônimo split:

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

Veja também implodir.

first

Devolve o primeiro elemento de matriz ou caráter de corda:

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

Ver também último, aleatório.

floor (int $precision=0)

Arredonda um número para uma determinada precisão.

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

Veja também Cessar, redondo.

firstUpper

Converte uma primeira letra de valor em maiúsculas. Requer extensão PHP mbstring.

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

Veja também capitalizar, inferior, superior.

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

O filtro agrupa os dados de acordo com diferentes critérios.

Neste exemplo, as linhas da tabela são agrupadas pela coluna categoryId. O resultado é uma matriz de matrizes em que a chave é o valor da coluna categoryId. Leia as instruções detalhadas.

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

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

implode (string $glue='')

Retorna um fio que é a concatenação das cordas na matriz. Alias para join.

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

Você também pode usar um pseudônimo join:

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

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

Indica um texto da esquerda por um determinado número de abas ou outros caracteres que especificamos no segundo argumento opcional. As linhas em branco não são indentadas.

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

Impressões:

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

last

Retorna o último elemento de matriz ou caráter de corda:

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

Veja também primeiro, aleatório.

length

Retorna o comprimento de um fio ou matriz.

• para cordas, ele retornará o comprimento em caracteres UTF-8
• para arrays, ele retornará a contagem dos itens
• para objetos que implementam a interface Countable, ele usará o valor de retorno da contagem()
• para objetos que implementam a interface IteratorAggregate, ele usará o valor de retorno do iterator_count()

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

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

Formata a data e a hora de acordo com a localidade, garantindo a exibição consistente e localizada dos dados de hora em diferentes idiomas e regiões. O filtro aceita a data como um carimbo de data/hora UNIX, uma cadeia de caracteres ou um objeto DateTimeInterface.

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

Se você usar o filtro sem nenhum parâmetro, ele emitirá a data no nível de formato longo, conforme explicado mais adiante.

a) Usando o formato

O parâmetro format descreve quais componentes de tempo devem ser exibidos. Ele usa códigos de letras, em que o 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 as convenções da localidade. Portanto, o formato é independente da localidade. Por exemplo, o formato yyyyMMMMd na localidade en_US gera April 15, 2024, enquanto na localidade cs_CZ gera 15. dubna 2024:

b) Uso de estilos predefinidos

Os parâmetros date e time determinam o nível de detalhe da exibição de data e hora. Você pode escolher entre vários níveis: full, long, medium, short. Você pode exibir apenas a data, apenas a hora ou ambas:

Para a data, você também pode usar o prefixo relative- (por exemplo, relative-short), que para datas próximas ao presente exibirá yesterday, today, ou tomorrow; caso contrário, será exibido da maneira padrão.

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

Consulte também date.

lower

Converte um valor para minúsculas. Requer extensão PHP mbstring.

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

Ver também capitalize, firstUpper, upper.

nocheck

Impede a higienização automática da URL. Latte verifica automaticamente se a variável contém uma URL da web (ou seja, protocolo HTTP/HTTPS) e impede a escrita de links que possam representar um risco de segurança.

Se o link usa um esquema diferente, como javascript: ou data:, e você tem certeza de seu conteúdo, você pode desativar a verificação via |nocheck.

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

<a href={$link}>checked</a>
<a href={$link|nocheck}>unchecked</a>

Impressões:

<a href="">checked</a>
<a href="javascript:window.close()">unchecked</a>

Veja também checkUrl.

noescape

Desativa a fuga automática.

{var $trustedHtmlString = '<b>hello</b>'}
Escaped: {$trustedHtmlString}
Unescaped: {$trustedHtmlString|noescape}

Impressões:

Escaped: <b>hello</b>
Unescaped: <b>hello</b>

O mau uso do filtro noescape pode levar a uma vulnerabilidade XSS! Nunca o use a menos que você esteja absolutamente seguro do que está fazendo e que o fio que você está imprimindo vem de uma fonte confiável.

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

Formata um número com um número especificado de casas decimais. Se a localidade estiver definida, serão usados os separadores decimais e de milhar correspondentes.

{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 que você defina a aparência dos números exatamente de acordo com suas necessidades. Ele requer uma localidade definida. O formato consiste em vários caracteres especiais, cuja descrição completa pode ser encontrada na documentação DecimalFormat:

• <c id=6/> dígito obrigatório, sempre exibido, mesmo que seja zero
• # dígito opcional, exibido somente se o número tiver um dígito naquele local
• @ dígito significativo, ajuda a exibir o número com um determinado número de dígitos significativos
• . marca onde o separador decimal deve estar (vírgula ou ponto, dependendo da localidade)
• , usado para separar grupos de dígitos, geralmente milhares
• % multiplica o número por 100 e adiciona o sinal de porcentagem

Vamos dar uma olhada em alguns exemplos. No primeiro exemplo, duas casas decimais são obrigatórias; no segundo, são opcionais. O terceiro exemplo mostra o preenchimento com zeros em ambos os lados, e 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 do ponto decimal, devem ser exibidos, arredondando o número, se necessário:

{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 por um caractere ;. Dessa forma, por exemplo, os números positivos podem ser exibidos com um 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 de acordo com as configurações de localidade. Por exemplo, em alguns países, uma vírgula é usada em vez de um ponto como separador decimal. Esse filtro considera isso automaticamente, portanto, você não precisa se preocupar com isso.

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

Coloca um cordel a um certo comprimento com outro cordel da esquerda.

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

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

Coloca um cordel a um certo comprimento com outro cordel da direita.

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

query

Dinamicamente, gera uma cadeia de consulta na URL:

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

Impressões:

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

As chaves com um valor de null são omitidas.

Veja também escapeUrl.

random

Devolve elemento aleatório de matriz ou caráter de corda:

{=[1, 2, 3, 4]|random}    {* example output: 3 *}
{='abcd'|random}          {* example output: 'b' *}

Ver também primeiro, último.

repeat (int $count)

Repete a seqüência x-vezes.

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

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

Substitui todas as ocorrências da cadeia de busca pela cadeia de substituição.

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

Substituições múltiplas podem ser feitas de uma só vez:

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

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

Substitui todas as ocorrências de acordo com a expressão regular.

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

reverse

Inverte seqüência ou matriz dada.

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

round (int $precision=0)

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

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

Veja também ceil, chão.

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

Extrai uma fatia de uma matriz ou um fio.

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

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

Se o início for não negativo, a seqüência começará nesse início na variável. Se o início for negativo, a seqüência começará tão longe do final da variável.

Se o comprimento for dado e for positivo, então a seqüência terá até muitos elementos nele. Se a variável for menor do que o comprimento, então somente os elementos variáveis disponíveis estarão presentes. Se o comprimento for dado e for negativo, então a seqüência interromperá que muitos elementos do final da variável. Se for omitido, então a seqüência terá tudo desde o offset até o final da variável.

O filtro reordenará e redefinirá as chaves da matriz inteira por padrão. Este comportamento pode ser alterado ajustando preserveKeys para 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 classifica os elementos de uma matriz ou iterador, preservando suas chaves associativas. Quando uma localidade é definida, a classificação segue suas regras, a menos que uma função de comparação personalizada seja especificada.

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

Array ordenados em ordem inversa.

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

Você pode especificar uma função de comparação personalizada para a classificação (o exemplo mostra como inverter a classificação do maior para o menor):

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

O filtro |sort também permite que você classifique os elementos por chave:

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

Se você precisar classificar uma tabela por uma coluna específica, poderá usar o parâmetro by. O valor 'name' no exemplo especifica que a classificação será feita por $row->name ou $row['name']dependendo do fato de $row ser uma matriz ou um objeto:

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

Você também pode definir uma função de retorno de chamada que determina o valor a ser classificado:

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

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

spaceless

Remove espaços em branco desnecessários da produção. Você também pode usar o pseudônimo strip.

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

Impressões:

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

stripHtml

Converte HTML em texto simples. Ou seja, remove as tags HTML e converte entidades HTML em texto.

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

O texto simples resultante pode naturalmente conter caracteres que representam tags HTML, por exemplo '<p>'|stripHtml é convertido para <p>. Nunca envie o texto resultante com |noescape, pois isso pode levar a uma vulnerabilidade de segurança.

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

Extrai uma fatia de um fio. Este filtro foi substituído por uma fatia de filtro.

{$string|substr: 1, 2}

translate (string $message, …$args)

Ela traduz expressões para outros idiomas. Para tornar o filtro disponível, é necessário instalar um tradutor. Você também pode usar as tags para a tradução.

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

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

Tire os personagens que lideram e seguem, por padrão, o espaço em branco.

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

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

Encurta um fio até o comprimento máximo dado, mas tenta preservar palavras inteiras. Se a cadeia for truncada, acrescenta elipses no final (isto pode ser alterado pelo 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 um valor em maiúsculas. Requer extensão PHP mbstring.

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

Veja também capitalizar, primeiroCima, mais baixo.

webalize

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 abre e desvia espaços em branco.

{var $s = 'Our 10. product'}
{$s|webalize}    {* outputs 'our-10-product' *}

Requer pacote nette/utils.