Filtri per latte
****************

.[perex]
I filtri sono funzioni che modificano o formattano i dati nella forma desiderata. Questo è un riassunto dei filtri incorporati disponibili.

.[table-latte-filters]
|## Trasformazione di stringhe/array
| `batch` | [elenca i dati lineari in una tabella |#batch]
| `breakLines` | [Inserisce le interruzioni di riga HTML prima di tutte le newline |#breakLines]
| `bytes` | [Formatta la dimensione in byte |#bytes]
| `clamp` | [blocca il valore all'intervallo |#clamp]
| `dataStream` | [Conversione del protocollo URI dei dati |#datastream]
| `date` | [formatta la data |#date]
| `explode` | [divide una stringa in base al delimitatore dato |#explode]
| `first` | [restituisce il primo elemento di un array o un carattere di una stringa |#first]
| `implode` | [unisce un array a una stringa |#implode]
| `indent` | [indenta il testo da sinistra con un certo numero di tabulazioni |#indent]
| `join` | [unisce un array a una stringa |#implode]
| `last` | [restituisce l'ultimo elemento di un array o un carattere di una stringa |#last]
| `length` | [restituisce la lunghezza di una stringa o di un array |#length]
| `number` | [formatta un numero |#number]
| `padLeft` | [completa la stringa alla lunghezza data da sinistra |#padLeft]
| `padRight` | [completa la stringa alla lunghezza data da destra |#padRight]
| `random` | [restituisce un elemento casuale di un array o un carattere di una stringa |#random]
| `repeat` | [ripete la stringa |#repeat]
| `replace` | [sostituisce tutte le occorrenze della stringa cercata con la sostituzione |#replace]
| `replaceRE` | [sostituisce tutte le occorrenze secondo l'espressione regolare |#replaceRE]
| `reverse` | [inverte una stringa o un array UTF-8 |#reverse]
| `slice` | [estrae una fetta di un array o di una stringa |#slice]
| `sort` | [ordina un array |#sort]
| `spaceless` | [rimuove gli spazi bianchi |#spaceless], simile al tag [spaceless |tags]
| `split` | [divide una stringa in base al delimitatore dato |#explode]
| `strip` | [rimuove gli spazi bianchi |#spaceless]
| `stripHtml` | [rimuove i tag HTML e converte le entità HTML in testo |#stripHtml]
| `substr` | [restituisce una parte della stringa |#substr]
| `trim` | [elimina gli spazi bianchi dalla stringa |#trim]
| `translate` | [traduzione in altre lingue |#translate]
| `truncate` | [accorcia la lunghezza preservando le parole intere |#truncate]
| `webalize` | [adatta la stringa UTF-8 alla forma utilizzata nell'URL |#webalize]

.[table-latte-filters]
|## Incasellamento delle lettere
| `capitalize` | [minuscolo, la prima lettera di ogni parola maiuscola |#capitalize]
| `firstUpper` | [rende la prima lettera maiuscola |#firstUpper]
| `lower` | [rende una stringa minuscola |#lower]
| `upper` | [rende una stringa maiuscola |#upper]

.[table-latte-filters]
|## Arrotondamento dei numeri
| `ceil` | [arrotonda un numero fino a una determinata precisione |#ceil]
| `floor` | [arrotonda un numero per difetto a una determinata precisione|#floor]
| `round` | [arrotonda un numero a una determinata precisione|#round]

.[table-latte-filters]
|## Escaping
| `escapeUrl` | [esegue l'escape di un parametro nell'URL |#escapeUrl]
| `noescape` | [stampa una variabile senza escape |#noescape]
| `query` | [genera una stringa di query nell'URL |#query]

Esistono anche filtri di escape per HTML (`escapeHtml` e `escapeHtmlComment`), XML (`escapeXml`), JavaScript (`escapeJs`), CSS (`escapeCss`) e iCalendar (`escapeICal`), che Latte utilizza autonomamente grazie all'[escape context-aware |safety-first#Context-aware escaping] e che non è necessario scrivere.

.[table-latte-filters]
|## Sicurezza
| `checkUrl` | [sanifica le stringhe da usare nell'attributo href |#checkUrl]
| `nocheck` | [impedisce la sanitizzazione automatica degli URL |#nocheck]

I [controlli |safety-first#link checking] degli attributi `src` e `href` vengono eseguiti [automaticamente |safety-first#link checking], quindi non è necessario usare il filtro `checkUrl`.


.[note]
Tutti i filtri incorporati funzionano con stringhe codificate UTF-8.


Uso .[#toc-usage]
=================

Latte consente di chiamare i filtri usando la notazione del segno di pipe (è ammesso lo spazio precedente):

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

I filtri possono essere concatenati, in tal caso si applicano in ordine da sinistra a destra:

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

I parametri vengono inseriti dopo il nome del filtro, separati da due punti o da una virgola:

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

I filtri possono essere applicati alle espressioni:

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

[I filtri personalizzati |extending-latte#filters] possono essere registrati in questo modo:

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

Lo utilizziamo in un modello come questo:

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


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


batch(int length, mixed item): array .[filter]{data-version:2.7}
----------------------------------------------------------------
Filtro che semplifica l'elencazione di dati lineari sotto forma di tabella. Restituisce un array di array con il numero di elementi indicato. Se si fornisce un secondo parametro, questo viene utilizzato per riempire gli elementi mancanti nell'ultima riga.

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

Stampa:

```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]
--------------------
Inserisce le interruzioni di riga HTML prima di tutti i newline.

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


bytes(int precision = 2) .[filter]
----------------------------------
Formatta una dimensione in byte in forma leggibile.

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


ceil(int precision = 0) .[filter]
---------------------------------
Arrotonda un numero fino a una determinata precisione.

```latte
{=3.4|ceil}         {* uscite 4      *}
{=135.22|ceil:1}    {* uscite 135.3  *}
{=135.22|ceil:3}    {* uscite 135.22 *}
```

Vedere anche [piano |#floor], [rotondo |#round].


capitalize .[filter]
--------------------
Restituisce una versione con titolo del valore. Le parole inizieranno con lettere maiuscole, tutti i caratteri rimanenti saranno minuscoli. Richiede l'estensione PHP `mbstring`.

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

Vedere anche [firstUpper |#firstUpper], [lower |#lower], [upper |#upper].


checkUrl .[filter]
------------------
Impone la sanitizzazione degli URL. Controlla se la variabile contiene un URL web (cioè un protocollo HTTP/HTTPS) e impedisce la scrittura di link che potrebbero rappresentare un rischio per la sicurezza.

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

Stampa:

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

Vedere anche [nocheck |#nocheck].


clamp(int|float min, int|float max) .[filter]{data-version:2.9}
---------------------------------------------------------------
Restituisce un valore limitato all'intervallo inclusivo di min e max.

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

Esiste anche come [funzione |functions#clamp].


dataStream(string mimetype = detect) .[filter]
----------------------------------------------
Converte il contenuto in uno schema URI di dati. Può essere usato per inserire immagini in HTML o CSS senza la necessità di collegare file esterni.

Poniamo di avere un'immagine in una variabile `$img = Image::fromFile('obrazek.gif')`, allora

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

Stampa ad esempio:

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

.[caution]
Richiede l'estensione PHP `fileinfo`.


date(string format) .[filter]
-----------------------------
Restituisce una data nel formato indicato, utilizzando le opzioni delle funzioni PHP [php:strftime] o [php:date]. Il filtro ottiene una data come timestamp UNIX, una stringa o un oggetto di tipo `DateTime`.

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


escapeUrl .[filter]
-------------------
Permette di separare una variabile da usare come parametro nell'URL.

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

Vedere anche [query |#query].


explode(string separator = '') .[filter]{data-version:2.10.2}
-------------------------------------------------------------
Divide una stringa in base al delimitatore dato e restituisce un array di stringhe. Alias di `split`.

```latte
{='one,two,three'|explode:','}    {* returns ['one', 'two', 'three'] *}
```

Se il delimitatore è una stringa vuota (valore predefinito), l'input verrà diviso in singoli caratteri:

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

È possibile utilizzare anche l'alias `split`:

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

Vedere anche [implode |#implode].


first .[filter]{data-version:2.10.2}
------------------------------------
Restituisce il primo elemento di una matrice o un carattere di una stringa:

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

Vedere anche [last |#last], [random |#random].


floor(int precision = 0) .[filter]
----------------------------------
Arrotonda un numero fino a una determinata precisione.

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

Vedere anche [ceil |#ceil], [round |#round].


firstUpper .[filter]
--------------------
Converte la prima lettera di un valore in maiuscolo. Richiede l'estensione PHP `mbstring`.

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

Vedere anche [capitalize |#capitalize], [lower |#lower], [upper |#upper].


implode(string glue = '') .[filter]
-----------------------------------
Restituisce una stringa che è la concatenazione delle stringhe dell'array. Alias di `join`.

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

È possibile utilizzare anche l'alias `join`: .{data-version:2.10.2}

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


indent(int level = 1, string char = "\t") .[filter]
---------------------------------------------------
Rientra un testo da sinistra di un determinato numero di tabulazioni o di altri caratteri, specificati nel secondo argomento opzionale. Le righe vuote non sono rientrate.

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

Stampa:

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


last .[filter]{data-version:2.10.2}
-----------------------------------
Restituisce l'ultimo elemento della matrice o il carattere della stringa:

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

Vedere anche [first |#first], [random |#random].


length .[filter]
----------------
Restituisce la lunghezza di una stringa o di un array.

- per le stringhe, restituisce la lunghezza in caratteri UTF-8
- per gli array, restituisce il conteggio degli elementi
- per gli oggetti che implementano l'interfaccia Countable, utilizzerà il valore di ritorno del metodo count()
- per gli oggetti che implementano l'interfaccia IteratorAggregate, utilizzerà il valore di ritorno dell'iterator_count()


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


lower .[filter]
---------------
Converte un valore in minuscolo. Richiede l'estensione PHP `mbstring`.

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

Vedere anche [capitalize |#capitalize], [firstUpper |#firstUpper], [upper |#upper].


nocheck .[filter]
-----------------
Impedisce la sanificazione automatica degli URL. Latte [controlla automaticamente |safety-first#Link checking] se la variabile contiene un URL web (cioè un protocollo HTTP/HTTPS) e impedisce la scrittura di link che potrebbero rappresentare un rischio per la sicurezza.

Se il link utilizza uno schema diverso, come `javascript:` o `data:`, e si è sicuri del suo contenuto, si può disabilitare il controllo tramite `|nocheck`.

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

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

Stampe:

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

Vedere anche [checkUrl |#checkUrl].


noescape .[filter]
------------------
Disabilita l'escape automatico.

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

Stampa:

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

.[warning]
L'uso improprio del filtro `noescape` può portare a una vulnerabilità XSS! Non utilizzatelo mai a meno che non siate **assolutamente sicuri** di quello che state facendo e che la stringa che state stampando provenga da una fonte affidabile.


number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter]
------------------------------------------------------------------------------------
Formatta un numero con un determinato numero di cifre decimali. È anche possibile specificare un carattere del punto decimale e del separatore delle migliaia.

```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]
-----------------------------------------------
Imbottisce una stringa di una certa lunghezza con un'altra stringa a partire da sinistra.

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


padRight(int length, string pad = ' ') .[filter]
------------------------------------------------
Imbottisce una stringa di una certa lunghezza con un'altra stringa proveniente da destra.

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


query  .[filter]{data-version:2.10}
-----------------------------------
Genera dinamicamente una stringa di query nell'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>
```

Stampa:

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

I tasti con valore `null` vengono omessi.

Vedere anche [escapeUrl |#escapeUrl].


random .[filter]{data-version:2.10.2}
-------------------------------------
Restituisce un elemento casuale di una matrice o un carattere di una stringa:

```latte
{=[1, 2, 3, 4]|random}    {* esempio di uscita: 3 *}
{='abcd'|random}          {* esempio di uscita: 'b' *}
```

Vedere anche [primo |#first], [ultimo |#last].


repeat(int count) .[filter]
---------------------------
Ripete la stringa x volte.

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


replace(string|array search, string replace = '') .[filter]
-----------------------------------------------------------
Sostituisce tutte le occorrenze della stringa di ricerca con la stringa di sostituzione.

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

È possibile effettuare più sostituzioni contemporaneamente: .{data-version:2.10.2}

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


replaceRE(string pattern, string replace = '') .[filter]
--------------------------------------------------------
Sostituisce tutte le occorrenze in base all'espressione regolare.

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


reverse .[filter]
-----------------
Inverte la stringa o l'array dato.

```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]
----------------------------------
Arrotonda un numero a una determinata precisione.

```latte
{=3.4|round}        {* uscite 3      *}
{=3.5|round}        {* uscite 4      *}
{=135.79|round:1}   {* uscite 135.8  *}
{=135.79|round:3}   {* uscite 135.79 *}
```

Vedere anche [ceil |#ceil], [floor |#floor].


slice(int start, int length = null, bool preserveKeys = false) .[filter]{data-version:2.10.2}
---------------------------------------------------------------------------------------------
Estrae una fetta di un array o di una stringa.

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

Il filtro slice funziona come la funzione PHP `array_slice` per gli array e `mb_substr` per le stringhe, con un fallback a `iconv_substr` in modalità UTF-8.

Se start è non negativo, la sequenza inizierà da quell'inizio nella variabile. Se start è negativo, la sequenza inizierà a quella distanza dalla fine della variabile.

Se la lunghezza è data ed è positiva, la sequenza conterrà fino a quel numero di elementi. Se la variabile è più corta della lunghezza, saranno presenti solo gli elementi disponibili della variabile. Se la lunghezza è data ed è negativa, la sequenza si fermerà a tanti elementi dalla fine della variabile. Se viene omesso, la sequenza conterrà tutti gli elementi dall'offset fino alla fine della variabile.

Per impostazione predefinita, Filter riordina e reimposta le chiavi dell'array di interi. Questo comportamento può essere modificato impostando preserveKeys su true. Le chiavi stringa vengono sempre conservate, indipendentemente da questo parametro.


sort  .[filter]{data-version:2.9}
---------------------------------
Filtro che ordina un array e mantiene l'associazione degli indici.

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

Array ordinato in ordine inverso.

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

È possibile passare la propria funzione di confronto come parametro: .{data-version:2.10.2}

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


spaceless  .[filter]{data-version:2.10.2}
-----------------------------------------
Rimuove gli spazi bianchi non necessari dall'output. Si può anche usare l'alias `strip`.

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

Stampa:

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


stripHtml .[filter]
-------------------
Converte l'HTML in testo normale. Ossia, rimuove i tag HTML e converte le entità HTML in testo.

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

Il testo normale risultante può naturalmente contenere caratteri che rappresentano tag HTML, ad esempio `'&lt;p&gt;'|stripHtml` viene convertito in `<p>`. Non inviare mai il testo risultante con `|noescape`, perché ciò potrebbe causare una vulnerabilità della sicurezza.


substr(int offset, int length = null) .[filter]
-----------------------------------------------
Estrae una fetta di una stringa. Questo filtro è stato sostituito da un filtro [a fetta |#slice].

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


translate(string message, ...args) .[filter]{data-version:3.0}
--------------------------------------------------------------
Traduce le espressioni in altre lingue. Per rendere disponibile il filtro, è necessario [impostare il traduttore |develop#TranslatorExtension]. Si possono anche usare i [tag per la traduzione |tags#Translation].

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


trim(string charlist = " \t\n\r\0\x0B\u{A0}") .[filter]
-------------------------------------------------------
Spogliare i caratteri iniziali e finali, per impostazione predefinita gli spazi bianchi.

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


truncate(int length, string append = '…') .[filter]
---------------------------------------------------
Accorcia una stringa alla lunghezza massima indicata, ma cerca di conservare le parole intere. Se la stringa è troncata, aggiunge un'ellissi alla fine (questo può essere cambiato con il secondo parametro).

```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 un valore in maiuscolo. Richiede l'estensione PHP `mbstring`.

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

Vedere anche [capitalize |#capitalize], [firstUpper |#firstUpper], [lower |#lower].


webalize .[filter]
------------------
Converte in ASCII.

Converte gli spazi in trattini. Rimuove i caratteri che non sono alfanumerici, sottolineati o trattini. Converte in minuscolo. Elimina anche gli spazi bianchi iniziali e finali.

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

.[caution]
Richiede il pacchetto [nette/utils |utils:].