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.
capitalize |
minúscula a primeira letra de cada palavra maiúscula |
firstUpper |
faz a primeira letra maiúscula |
lower |
faz uma minúscula |
upper |
faz uma maiúscula de corda |
ceil |
arredonda um número até uma determinada precisão |
floor |
arredonda um número para uma determinada precisão |
round |
arredonda um número para uma dada precisão |
escapeUrl |
parâmetro de fuga no URL |
noescape |
imprime uma variável sem fugir |
query |
gera uma cadeia de consulta na URL |
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.
checkUrl |
higieniza cadeia para uso dentro do atributo href |
nocheck |
previne a higienização automática da URL |
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 *}
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' *}
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 *}
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:
Year | y / yy / yyyy |
2024 / 24 / 2024 |
Mês | M / MM / MMM / MMMM |
8 / 08 / ago. / agosto |
Dia | d / dd / E / EEEE |
1 / 01 / domingo / domingo |
Hora | j / H / h |
preferencial / 24 horas / 12 horas |
Minuto | m / mm |
5 / 05 (2 dígitos quando combinado com segundos) |
Segundo | s / ss |
8 / 08 (2 dígitos quando combinados com os minutos) |
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
:
locale: | pt-PT | en_US |
---|---|---|
format: 'dMy' |
10/08/2024 | 8/10/2024 |
format: 'yM' |
08/2024 | 8/2024 |
format: 'yyyyMMMM' |
agosto de 2024 | August 2024 |
format: 'MMMM' |
agosto | August |
format: 'jm' |
17:54 | 5:54 PM |
format: 'Hm' |
17:54 | 17:54 |
format: 'hm' |
5:54 da tarde | 5:54 PM |
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:
locale: | pt-PT | en_US |
---|---|---|
date: short |
23/01/78 | 1/23/78 |
date: medium |
23/01/1978 | Jan 23, 1978 |
date: long |
23 de janeiro de 1978 | January 23, 1978 |
date: full |
segunda-feira, 23 de janeiro de 1978 | Monday, January 23, 1978 |
time: short |
08:30 | 8:30 AM |
time: medium |
08:30:59 | 8:30:59 AM |
time: long |
08:30:59 CET | 8:30:59 AM GMT+1 |
date: short, time: short |
23/01/78, 08:30 | 1/23/78, 8:30 AM |
date: medium, time: short |
23/01/1978, 08:30 | Jan 23, 1978, 8:30 AM |
date: long, time: short |
23 de janeiro de 1978 às 08:30 | January 23, 1978 at 8:30 AM |
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&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' *}
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 *}
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 < 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.