Filtros de Latte
****************

.[perex]
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.

.[table-latte-filters]
|## Transformação de corda / matriz
| `batch` | [listando dados lineares em uma tabela |#batch]
| `breakLines` | [Insere quebras de linha HTML antes de todas as novas linhas |#breakLines]
| `bytes` | [formatos em bytes |#bytes]
| `clamp` | [valor dos grampos para a faixa |#clamp]
| `dataStream` | [Conversão do protocolo Data URI |#datastream]
| `date` | [formatos data |#date]
| `explode` | [divide um fio pelo delimitador dado |#explode]
| `first` | [devolve o primeiro elemento de matriz ou caráter de cadeia |#first]
| `implode` | [junta um conjunto a um cordão |#implode]
| `indent` | [traça o texto da esquerda com o número de abas |#indent]
| `join` | [junta um conjunto a um cordão |#implode]
| `last` | [retorna o último elemento de matriz ou caráter de cadeia |#last]
| `length` | [devolve o comprimento de um fio ou matriz |#length]
| `number` | [número de formatos |#number]
| `padLeft` | [completa o cordel a dado comprimento a partir da esquerda |#padLeft]
| `padRight` | [completa o cordel a dado comprimento a partir da direita |#padRight]
| `random` | [retorna elemento aleatório de matriz ou caráter de cadeia |#random]
| `repeat` | [repete o fio |#repeat]
| `replace` | [substitui todas as ocorrências da cadeia de busca com a substituição |#replace]
| `replaceRE` | [substitui todas as ocorrências de acordo com a expressão regular |#replaceRE]
| `reverse` | [inverte uma corda ou matriz UTF-8 |#reverse]
| `slice` | [extrai uma fatia de uma matriz ou um fio |#slice]
| `sort` | [classifica uma série |#sort]
| `spaceless` | [remove o espaço em branco |#spaceless], semelhante à etiqueta [sem espaçamento |tags]
| `split` | [divide um fio pelo delimitador dado |#explode]
| `strip` | [remove o espaço em branco |#spaceless]
| `stripHtml` | [remove as tags HTML e converte entidades HTML em texto |#stripHtml]
| `substr` | [devolve parte da cadeia |#substr]
| `trim` | [tira o espaço em branco da corda |#trim]
| `translate` | [tradução para outros idiomas |#translate]
| `truncate` | [encurta o comprimento preservando palavras inteiras |#truncate]
| `webalize` | [ajusta a corda UTF-8 à forma usada na URL |#webalize]

.[table-latte-filters]
|## Caixa de papelão
| `capitalize` | [minúscula a primeira letra de cada palavra maiúscula |#capitalize]
| `firstUpper` | [faz a primeira letra maiúscula |#firstUpper]
| `lower` | [faz uma minúscula |#lower]
| `upper` | [faz uma maiúscula de corda |#upper]

.[table-latte-filters]
|### Arredondamento de números
| `ceil` | [arredonda um número até uma determinada precisão |#ceil]
| `floor` | [arredonda um número para uma determinada precisão |#floor]
| `round` | [arredonda um número para uma dada precisão |#round]

.[table-latte-filters]
|## Escapando
| `escapeUrl` | [parâmetro de fuga no URL |#escapeUrl]
| `noescape` | [imprime uma variável sem fugir |#noescape]
| `query` | [gera uma cadeia de consulta na URL |#query]

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 |safety-first#Context-aware escaping] e você não precisa escrevê-los.

.[table-latte-filters]
|### Segurança
| `checkUrl` | [higieniza cadeia para uso dentro do atributo href |#checkUrl]
| `nocheck` | [previne a higienização automática da URL |#nocheck]

Latte os atributos `src` e `href` [verificam automaticamente |safety-first#link checking], de modo que quase não é necessário usar o filtro `checkUrl`.


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


Utilização .[#toc-usage]
========================

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

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

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

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

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

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

Os filtros podem ser aplicados por expressão:

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

[Os filtros personalizados |extending-latte#filters] podem ser registrados desta forma:

```php
$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:

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


Filtros .[#toc-filters]
=======================


batch(int length, mixed item): array .[filter]
----------------------------------------------
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.

```latte
{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:

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


breakLines .[filter]
--------------------
Insere quebras de linha HTML antes de todas as novas linhas.

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


bytes(int precision = 2) .[filter]
----------------------------------
Formata um tamanho em bytes de forma legível para o ser humano.

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


ceil(int precision = 0) .[filter]
---------------------------------
Arredonda um número até uma determinada precisão.

```latte
{=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 |#floor], [redondo |#round].


capitalize .[filter]
--------------------
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`.

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

Ver também [firstUpper |#firstUpper], [lower |#lower], [upper |#upper].


checkUrl .[filter]
------------------
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.

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

Impressões:

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

Veja também [nocheck |#nocheck].


clamp(int|float min, int|float max) .[filter]
---------------------------------------------
Retorna o valor fixado para a faixa inclusiva de min e max.

```latte
{$level|clamp: 0, 255}
```

Também existe como [função |functions#clamp].


dataStream(string mimetype = detect) .[filter]
----------------------------------------------
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

```latte
<img src={$img|dataStream}>
```

Impressões, por exemplo:

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

.[caution]
Requer extensão PHP `fileinfo`.


date(string format) .[filter]
-----------------------------
Retorna uma data no formato dado usando as opções de [php:strftime] ou [php:date] funções PHP. O filtro recebe uma data como um carimbo de tempo UNIX, uma string ou um objeto do tipo `DateTime`.

```latte
{$today|date:'%d.%m.%Y'}
{$today|date:'j. n. Y'}
```


escapeUrl .[filter]
-------------------
Escapa a uma variável para ser usada como parâmetro na URL.

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

Veja também [consulta |#query].


explode(string separator = '') .[filter]
----------------------------------------
Divide um fio pelo delimitador dado e retorna um conjunto de fios. Alias para `split`.

```latte
{='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:

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

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

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

Veja também [implodir |#implode].


first .[filter]
---------------
Devolve o primeiro elemento de matriz ou caráter de corda:

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

Ver também [último |#last], [aleatório |#random].


floor(int precision = 0) .[filter]
----------------------------------
Arredonda um número para uma determinada precisão.

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

Veja também [Cessar |#ceil], [redondo |#round].


firstUpper .[filter]
--------------------
Converte uma primeira letra de valor em maiúsculas. Requer extensão PHP `mbstring`.

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

Veja também [capitalizar |#capitalize], [inferior |#lower], [superior |#upper].


implode(string glue = '') .[filter]
-----------------------------------
Retorna um fio que é a concatenação das cordas na matriz. Alias para `join`.

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

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

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


indent(int level = 1, string char = "\t") .[filter]
---------------------------------------------------
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.

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

Impressões:

```latte
<div>
	<p>Hello</p>
</div>
```


last .[filter]
--------------
Retorna o último elemento de matriz ou caráter de corda:

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

Veja também [primeiro |#first], [aleatório |#random].


length .[filter]
----------------
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()


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


lower .[filter]
---------------
Converte um valor para minúsculas. Requer extensão PHP `mbstring`.

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

Ver também [capitalize |#capitalize], [firstUpper |#firstUpper], [upper |#upper].


nocheck .[filter]
-----------------
Impede a higienização automática da URL. Latte [verifica automaticamente |safety-first#Link checking] 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`.

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

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

Impressões:

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

Veja também [checkUrl |#checkUrl].


noescape .[filter]
------------------
Desativa a fuga automática.

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

Impressões:

```latte
Escaped: &lt;b&gt;hello&lt;/b&gt;
Unescaped: <b>hello</b>
```

.[warning]
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 = ',') .[filter]
------------------------------------------------------------------------------------
Formata um número para um determinado número de casas decimais. Você também pode especificar um caractere do separador de casas decimais e de milhares.

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


padLeft(int length, string pad = ' ') .[filter]
-----------------------------------------------
Coloca um cordel a um certo comprimento com outro cordel da esquerda.

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


padRight(int length, string pad = ' ') .[filter]
------------------------------------------------
Coloca um cordel a um certo comprimento com outro cordel da direita.

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


query  .[filter]
----------------
Dinamicamente, gera uma cadeia de consulta na URL:

```latte
<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:

```latte
<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 |#escapeUrl].


random .[filter]
----------------
Devolve elemento aleatório de matriz ou caráter de corda:

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

Ver também [primeiro |#first], [último |#last].


repeat(int count) .[filter]
---------------------------
Repete a seqüência x-vezes.

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


replace(string|array search, string replace = '') .[filter]
-----------------------------------------------------------
Substitui todas as ocorrências da cadeia de busca pela cadeia de substituição.

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

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

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


replaceRE(string pattern, string replace = '') .[filter]
--------------------------------------------------------
Substitui todas as ocorrências de acordo com a expressão regular.

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


reverse .[filter]
-----------------
Inverte seqüência ou matriz dada.

```latte
{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) .[filter]
----------------------------------
Arredonda um número para uma dada precisão.

```latte
{=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 |#ceil], [chão |#floor].


slice(int start, int length = null, bool preserveKeys = false) .[filter]
------------------------------------------------------------------------
Extrai uma fatia de uma matriz ou um fio.

```latte
{='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  .[filter]
---------------
Filtro que ordena uma matriz e mantém a associação de índices.

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

Array ordenados em ordem inversa.

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

Você pode passar sua própria função de comparação como um parâmetro:

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


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

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

Impressões:

```latte
<ul> <li>Hello</li> </ul>
```


stripHtml .[filter]
-------------------
Converte HTML em texto simples. Ou seja, remove as tags HTML e converte entidades HTML em texto.

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

O texto simples resultante pode naturalmente conter caracteres que representam tags HTML, por exemplo `'&lt;p&gt;'|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) .[filter]
-----------------------------------------------
Extrai uma fatia de um fio. Este filtro foi substituído por uma [fatia de |#slice] filtro.

```latte
{$string|substr: 1, 2}
```


translate(string message, ...args) .[filter]
--------------------------------------------
Ela traduz expressões para outros idiomas. Para tornar o filtro disponível, é necessário [instalar um tradutor |develop#TranslatorExtension]. Você também pode usar as [tags para a tradução |tags#Translation].

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


trim(string charlist = " \t\n\r\0\x0B\u{A0}") .[filter]
-------------------------------------------------------
Tire os personagens que lideram e seguem, por padrão, o espaço em branco.

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


truncate(int length, string append = '…') .[filter]
---------------------------------------------------
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).

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


upper .[filter]
---------------
Converte um valor em maiúsculas. Requer extensão PHP `mbstring`.

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

Veja também [capitalizar |#capitalize], [primeiroCima |#firstUpper], [mais baixo |#lower].


webalize .[filter]
------------------
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.

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

.[caution]
Requer pacote [nette/utils |utils:].