Filtri per latte

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

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 e che non è necessario scrivere.

I controlli degli attributi src e href vengono eseguiti automaticamente, quindi non è necessario usare il filtro checkUrl.

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

Uso

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

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

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

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

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

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

I filtri possono essere applicati alle espressioni:

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

I filtri personalizzati possono essere registrati in questo modo:

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

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

Filtri

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

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.

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

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

Vedere anche gruppo e tag iterateWhile.

breakLines

Inserisce le interruzioni di riga HTML prima di tutti i newline.

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

bytes (int $precision=2)

Formatta la dimensione in byte in una forma leggibile. Se il locale è impostato, vengono utilizzati i corrispondenti separatori decimali e delle migliaia.

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

ceil (int $precision=0)

Arrotonda un numero fino a una determinata precisione.

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

Vedere anche piano, rotondo.

capitalize

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

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

Vedere anche firstUpper, lower, upper.

checkUrl

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.

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

Stampa:

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

Vedere anche nocheck.

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

Restituisce un valore limitato all'intervallo inclusivo di min e max.

{$level|clamp: 0, 255}

Esiste anche come funzione.

dataStream (string $mimetype=detect)

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

<img src={$img|dataStream}>

Stampa ad esempio:

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

Richiede l'estensione PHP fileinfo.

date (string $format)

Formatta la data e l'ora secondo la maschera utilizzata dalla funzione PHP date. Il filtro accetta la data in formato UNIX timestamp, come stringa o come oggetto DateTimeInterface.

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

Vedere anche localDate.

escapeUrl

Permette di separare una variabile da usare come parametro nell'URL.

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

Vedere anche query.

explode (string $separator='')

Divide una stringa in base al delimitatore dato e restituisce un array di stringhe. Alias di split.

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

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

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

È possibile utilizzare anche l'alias split:

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

Vedere anche implode.

first

Restituisce il primo elemento di una matrice o un carattere di una stringa:

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

Vedere anche last, random.

floor (int $precision=0)

Arrotonda un numero fino a una determinata precisione.

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

Vedere anche ceil, round.

firstUpper

Converte la prima lettera di un valore in maiuscolo. Richiede l'estensione PHP mbstring.

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

Vedere anche capitalize, lower, upper.

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

Il filtro raggruppa i dati in base a diversi criteri.

In questo esempio, le righe della tabella sono raggruppate in base alla colonna categoryId. L'output è un array di array in cui la chiave è il valore della colonna categoryId. Leggete le istruzioni dettagliate.

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

Vedere anche batch, la funzione group e il tag iterateWhile.

implode (string $glue='')

Restituisce una stringa che è la concatenazione delle stringhe dell'array. Alias di join.

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

È possibile utilizzare anche l'alias join:

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

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

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.

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

Stampa:

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

last

Restituisce l'ultimo elemento della matrice o il carattere della stringa:

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

Vedere anche first, random.

length

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

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

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

Formatta la data e l'ora in base al locale, garantendo una visualizzazione coerente e localizzata dei dati temporali in diverse lingue e regioni. Il filtro accetta la data come timestamp UNIX, stringa o oggetto DateTimeInterface.

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

Se si utilizza il filtro senza alcun parametro, verrà emessa la data nel livello di formato lungo, come spiegato più avanti.

a) Utilizzo del formato

Il parametro format descrive quali componenti dell'ora devono essere visualizzati. Utilizza codici di lettere, il cui numero di ripetizioni influisce sull'ampiezza dell'output:

L'ordine dei codici nel formato non ha importanza, poiché l'ordine dei componenti sarà visualizzato in base alle convenzioni del locale. Pertanto, il formato è indipendente dal locale. Ad esempio, il formato yyyyMMMMd nel locale en_US produce April 15, 2024, mentre nel locale cs_CZ produce 15. dubna 2024:

b) Utilizzo di stili preimpostati

I parametri date e time determinano il livello di dettaglio della visualizzazione di data e ora. È possibile scegliere tra diversi livelli: full, long, medium, short. È possibile visualizzare solo la data, solo l'ora o entrambe:

Per la data si può anche usare il prefisso relative- (ad esempio, relative-short), che per le date vicine al presente visualizzerà yesterday, today, o tomorrow; altrimenti, verrà visualizzato nel modo standard.

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

Vedere anche data.

lower

Converte un valore in minuscolo. Richiede l'estensione PHP mbstring.

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

Vedere anche capitalize, firstUpper, upper.

nocheck

Impedisce la sanificazione automatica degli URL. Latte controlla automaticamente 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.

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

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

Stampe:

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

Vedere anche checkUrl.

noescape

Disabilita l'escape automatico.

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

Stampa:

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

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=',')

Formatta un numero con un numero specificato di cifre decimali. Se il locale è impostato, vengono utilizzati i corrispondenti separatori decimali e delle migliaia.

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

Il parametro format consente di definire l'aspetto dei numeri esattamente secondo le proprie esigenze. Richiede un locale impostato. Il formato consiste in diversi caratteri speciali, la cui descrizione completa si trova nella documentazione DecimalFormat:

• <c id=6/> cifra obbligatoria, sempre visualizzata anche se è zero
• # cifra opzionale, visualizzata solo se il numero ha una cifra in quel posto
• @ cifra significativa, aiuta a visualizzare il numero con un certo numero di cifre significative
• . segna la posizione del separatore decimale (virgola o punto, a seconda del locale)
• , si usa per separare gruppi di cifre, di solito le migliaia
• % moltiplica il numero per 100 e aggiunge il segno di percentuale

Vediamo alcuni esempi. Nel primo esempio, le due cifre decimali sono obbligatorie; nel secondo, sono facoltative. Il terzo esempio mostra un'imbottitura con zeri su entrambi i lati, mentre il quarto visualizza solo le cifre esistenti:

{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 *}

Le cifre significative determinano il numero di cifre da visualizzare, indipendentemente dal punto decimale, arrotondando il numero se necessario:

{1234|number: '@@'}             {* 1200 *}
{1234|number: '@@@'}            {* 1230 *}
{1234|number: '@@@#'}           {* 1234 *}
{1.2345|number: '@@@'}          {* 1.23 *}
{0.00123|number: '@@'}          {* 0.0012 *}

Un modo semplice per visualizzare un numero come percentuale. Il numero viene moltiplicato per 100 e viene aggiunto il segno %:

{0.1234|number: '#.##%'}        {* 12.34% *}

Possiamo definire un formato diverso per i numeri positivi e negativi, separati da un carattere ;. In questo modo, ad esempio, i numeri positivi possono essere visualizzati con il segno +:

{42|number: '#.##;(#.##)'}      {* 42 *}
{-42|number: '#.##;(#.##)'}     {* (42) *}
{42|number: '+#.##;-#.##'}      {* +42 *}
{-42|number: '+#.##;-#.##'}     {* -42 *}

Ricordate che l'aspetto effettivo dei numeri può variare a seconda delle impostazioni locali. Ad esempio, in alcuni Paesi si usa una virgola al posto del punto come separatore decimale. Questo filtro ne tiene conto automaticamente, quindi non è necessario preoccuparsene.

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

Imbottisce una stringa di una certa lunghezza con un'altra stringa a partire da sinistra.

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

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

Imbottisce una stringa di una certa lunghezza con un'altra stringa proveniente da destra.

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

query

Genera dinamicamente una stringa di query nell'URL:

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

Stampa:

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

random

Restituisce un elemento casuale di una matrice o un carattere di una stringa:

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

Vedere anche primo, ultimo.

repeat (int $count)

Ripete la stringa x volte.

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

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

Sostituisce tutte le occorrenze della stringa di ricerca con la stringa di sostituzione.

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

È possibile effettuare più sostituzioni contemporaneamente:

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

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

Sostituisce tutte le occorrenze in base all'espressione regolare.

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

reverse

Inverte la stringa o l'array dato.

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

Arrotonda un numero a una determinata precisione.

{=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, floor.

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

Estrae una fetta di un array o di una stringa.

{='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 (?Closure $comparison, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false)

Il filtro ordina gli elementi di un array o di un iteratore preservandone le chiavi associative. Quando viene impostato un locale, l'ordinamento segue le sue regole, a meno che non venga specificata una funzione di confronto personalizzata.

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

Array ordinato in ordine inverso.

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

È possibile specificare una funzione di confronto personalizzata per l'ordinamento (l'esempio mostra come invertire l'ordinamento dal più grande al più piccolo):

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

Il filtro |sort consente anche di ordinare gli elementi per chiave:

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

Se si desidera ordinare una tabella in base a una colonna specifica, è possibile utilizzare il parametro by. Il valore 'name' nell'esempio specifica che l'ordinamento sarà effettuato da $row->name o da $row['name']a seconda che $row sia una matrice o un oggetto:

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

Si può anche definire una funzione di callback che determina il valore da ordinare:

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

Il parametro byKey può essere utilizzato allo stesso modo.

spaceless

Rimuove gli spazi bianchi non necessari dall'output. Si può anche usare l'alias strip.

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

Stampa:

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

stripHtml

Converte l'HTML in testo normale. Ossia, rimuove i tag HTML e converte le entità HTML in testo.

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

Il testo normale risultante può naturalmente contenere caratteri che rappresentano tag HTML, ad esempio '<p>'|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)

Estrae una fetta di una stringa. Questo filtro è stato sostituito da un filtro a fetta.

{$string|substr: 1, 2}

translate (string $message, …$args)

Traduce le espressioni in altre lingue. Per rendere disponibile il filtro, è necessario impostare il traduttore. Si possono anche usare i tag per la traduzione.

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

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

Spogliare i caratteri iniziali e finali, per impostazione predefinita gli spazi bianchi.

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

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

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

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

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

Vedere anche capitalize, firstUpper, lower.

webalize

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.

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

Richiede il pacchetto nette/utils.