Filtres Latte

Dans les templates, nous pouvons utiliser des fonctions qui aident à modifier ou reformater les données dans leur forme finale. Nous les appelons filtres.

De plus, il existe des filtres d'échappement pour HTML (escapeHtml et escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) et iCalendar (escapeICal), que Latte utilise lui-même grâce à l'échappement contextuel et que vous n'avez pas besoin d'écrire.

Les attributs Latte src et href vérifient automatiquement, donc vous n'avez presque jamais besoin d'utiliser le filtre checkUrl.

Tous les filtres par défaut sont conçus pour les chaînes encodées en UTF‑8.

Utilisation

Les filtres s'écrivent après une barre verticale (il peut y avoir un espace avant) :

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

Les filtres (appelés helpers dans les anciennes versions) peuvent être chaînés et sont alors appliqués dans l'ordre de gauche à droite :

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

Les paramètres sont spécifiés après le nom du filtre, séparés par des deux-points ou des virgules :

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

Les filtres peuvent également être appliqués à une expression :

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

Les filtres personnalisés peuvent être enregistrés de cette manière :

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

Dans le template, on l'appelle ensuite comme ceci :

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

Filtres

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

Filtre qui simplifie l'affichage de données linéaires sous forme de tableau. Retourne un tableau de tableaux avec le nombre d'éléments spécifié. Si vous spécifiez le deuxième paramètre, il sera utilisé pour compléter les éléments manquants sur la dernière ligne.

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

Affiche :

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

Voir aussi group et la balise iterateWhile.

breakLines

Ajoute la balise HTML <br> avant chaque caractère de nouvelle ligne.

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

bytes (int $precision=2)

Formate la taille en octets dans un format lisible par l'homme. Si les paramètres régionaux sont définis, les séparateurs décimaux et de milliers correspondants sont utilisés.

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

ceil (int $precision=0)

Arrondit un nombre vers le haut à la précision donnée.

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

Voir aussi floor, round.

capitalize

Les mots commenceront par des majuscules, tous les caractères restants seront en minuscules. Nécessite l'extension PHP mbstring.

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

Voir aussi firstUpper, lower, upper.

checkUrl

Force le nettoyage de l'adresse URL. Vérifie si la variable contient une URL web (c'est-à-dire protocole HTTP/HTTPS) et empêche l'affichage de liens qui pourraient présenter un risque de sécurité.

{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>vérifié</a>
<a data-href={$link}>non vérifié</a>

Affiche :

<a data-href="">vérifié</a>
<a data-href="javascript:window.close()">non vérifié</a>

Voir aussi nocheck.

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

Limite la valeur à la plage inclusive donnée min et max.

{$level|clamp: 0, 255}

Existe aussi comme fonction.

dataStream (string $mimetype=detect)

Convertit le contenu en schéma data URI. Permet d'insérer des images dans HTML ou CSS sans avoir besoin de lier des fichiers externes.

Ayons une image dans la variable $img = Image::fromFile('image.gif'), alors

<img src={$img|dataStream}>

Affiche par exemple :

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

Nécessite l'extension PHP fileinfo.

date (string $format)

Formate la date et l'heure selon le masque utilisé par la fonction PHP date. Le filtre accepte la date au format timestamp UNIX, comme chaîne ou objet de type DateTimeInterface.

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

Voir aussi localDate.

escapeUrl

Échappe la variable pour une utilisation en tant que paramètre dans une URL.

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

Voir aussi query.

explode (string $separator='')

Divise une chaîne en un tableau selon le délimiteur. Alias pour split.

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

Si le délimiteur est une chaîne vide (valeur par défaut), l'entrée sera divisée en caractères individuels :

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

Vous pouvez également utiliser l'alias split :

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

Voir aussi implode.

first

Retourne le premier élément d'un tableau ou caractère d'une chaîne :

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

Voir aussi last, random.

floor (int $precision=0)

Arrondit un nombre vers le bas à la précision donnée.

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

Voir aussi ceil, round.

firstUpper

Convertit la première lettre en majuscule. Nécessite l'extension PHP mbstring.

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

Voir aussi capitalize, lower, upper.

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

Le filtre regroupe les données selon différents critères.

Dans cet exemple, les lignes du tableau sont regroupées par la colonne categoryId. La sortie est un tableau de tableaux où la clé est la valeur de la colonne categoryId. Lisez le tutoriel détaillé.

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

Voir aussi batch, la fonction group et la balise iterateWhile.

implode (string $glue='')

Retourne une chaîne qui est la concaténation des éléments de la séquence. Alias pour join.

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

Vous pouvez également utiliser l'alias join :

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

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

Indente le texte depuis la gauche d'un nombre donné de tabulations ou d'autres caractères que nous pouvons spécifier dans le deuxième argument. Les lignes vides ne sont pas indentées.

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

Affiche :

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

last

Retourne le dernier élément d'un tableau ou caractère d'une chaîne :

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

Voir aussi first, random.

length

Retourne la longueur d'une chaîne ou d'un tableau.

• pour les chaînes, retourne la longueur en caractères UTF‑8
• pour les tableaux, retourne le nombre d'éléments
• pour les objets qui implémentent l'interface Countable, utilise la valeur de retour de la méthode count()
• pour les objets qui implémentent l'interface IteratorAggregate, utilise la valeur de retour de la fonction iterator_count()

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

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

Formate la date et l'heure selon les paramètres régionaux, ce qui assure un affichage cohérent et localisé des données temporelles à travers différentes langues et régions. Le filtre accepte la date comme timestamp UNIX, chaîne ou objet de type DateTimeInterface.

{$date|localDate}                  {* 15 avril 2024 *}
{$date|format: yM}                 {* 4/2024 *}
{$date|localDate: date: medium}    {* 15/04/2024 *}

Si vous utilisez le filtre sans paramètres, la date sera affichée au niveau long, voir ci-dessous.

a) utilisation du format

Le paramètre format décrit quels composants temporels doivent être affichés. Il utilise pour cela des codes alphabétiques, dont le nombre de répétitions influence la largeur de la sortie :

L'ordre des codes dans le format n'a pas d'importance, car l'ordre des composants sera affiché selon les conventions des paramètres régionaux. Le format est donc indépendant de ceux-ci. Par exemple, le format yyyyMMMMd dans l'environnement en_US affichera April 15, 2024, tandis que dans l'environnement fr_FR il affichera 15 avril 2024 :

b) utilisation de styles prédéfinis

Les paramètres date et time déterminent le niveau de détail avec lequel la date et l'heure doivent être affichées. Vous pouvez choisir parmi plusieurs niveaux : full, long, medium, short. Il est possible de n'afficher que la date, que l'heure, ou les deux :

Pour la date, vous pouvez en plus utiliser le préfixe relative- (par ex. relative-short), qui pour les dates proches de l'actuelle affichera hier, aujourd'hui ou demain, sinon elle sera affichée de manière standard.

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

Voir aussi date.

lower

Convertit une chaîne en minuscules. Nécessite l'extension PHP mbstring.

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

Voir aussi capitalize, firstUpper, upper.

nocheck

Empêche le nettoyage automatique de l'adresse URL. Latte vérifie automatiquement si la variable contient une URL web (c'est-à-dire protocole HTTP/HTTPS) et empêche l'affichage de liens qui pourraient présenter un risque de sécurité.

Si le lien utilise un autre schéma, par ex. javascript: ou data:, et que vous êtes sûr de son contenu, vous pouvez désactiver la vérification à l'aide de |nocheck.

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

<a href={$link}>vérifié</a>
<a href={$link|nocheck}>non vérifié</a>

Affiche :

<a href="">vérifié</a>
<a href="javascript:window.close()">non vérifié</a>

Voir aussi checkUrl.

noescape

Désactive l'échappement automatique.

{var $trustedHtmlString = '<b>hello</b>'}
Échappé : {$trustedHtmlString}
Non échappé : {$trustedHtmlString|noescape}

Affiche :

Échappé : <b>hello</b>
Non échappé : <b>hello</b>

Une mauvaise utilisation du filtre noescape peut entraîner une vulnérabilité XSS ! Ne l'utilisez jamais si vous n'êtes pas absolument sûr de ce que vous faites et que la chaîne affichée provient d'une source fiable.

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

Formate un nombre à un certain nombre de décimales. Si les paramètres régionaux sont définis, les séparateurs décimaux et de milliers correspondants sont utilisés.

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

Le paramètre format permet de définir l'apparence des nombres exactement selon vos besoins. Pour cela, il est nécessaire d'avoir défini les paramètres régionaux. Le format se compose de plusieurs caractères spéciaux, dont la description complète se trouve dans la documentation DecimalFormat :

• 0 chiffre obligatoire, s'affiche toujours, même s'il s'agit d'un zéro
• # chiffre facultatif, ne s'affiche que si le nombre existe réellement à cet endroit
• @ chiffre significatif, aide à afficher le nombre avec un certain nombre de chiffres valides
• . indique où doit se trouver la virgule décimale (ou le point, selon le pays)
• , sert à séparer les groupes de chiffres, le plus souvent les milliers
• % multiplie le nombre par 100× et ajoute le signe pourcentage

Regardons quelques exemples. Dans le premier exemple, deux décimales sont obligatoires, dans le second, elles sont facultatives. Le troisième exemple montre le remplissage avec des zéros à gauche et à droite, le quatrième n'affiche que les chiffres existants :

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

Les chiffres significatifs déterminent combien de chiffres, indépendamment de la virgule décimale, doivent être affichés, en arrondissant :

{1234|number: '@@'}             {* 1200 *}
{1234|number: '@@@'}            {* 1230 *}
{1234|number: '@@@#'}           {* 1234 *}
{1.2345|number: '@@@'}          {* 1,23 *}
{0.00123|number: '@@'}          {* 0,0012 *}

Un moyen facile d'afficher un nombre en pourcentage. Le nombre est multiplié par 100× et le signe % est ajouté :

{0.1234|number: '#.##%'}        {* 12,34 % *}

Nous pouvons définir un format différent pour les nombres positifs et négatifs, séparés par le caractère ;. De cette manière, on peut par exemple définir que les nombres positifs doivent être affichés avec le signe + :

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

N'oubliez pas que l'apparence réelle des nombres peut varier en fonction des paramètres du pays. Par exemple, dans certains pays, on utilise une virgule au lieu d'un point comme séparateur décimal. Ce filtre en tient compte automatiquement et vous n'avez rien à faire.

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

Complète une chaîne à une certaine longueur avec une autre chaîne depuis la gauche.

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

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

Complète une chaîne à une certaine longueur avec une autre chaîne depuis la droite.

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

query

Génère dynamiquement la chaîne de requête dans une URL :

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

Affiche :

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

Les clés avec la valeur null sont omises.

Voir aussi escapeUrl.

random

Retourne un élément aléatoire d'un tableau ou caractère d'une chaîne :

{=[1, 2, 3, 4]|random}    {* affiche par ex. : 3 *}
{='abcd'|random}          {* affiche par ex. : 'b' *}

Voir aussi first, last.

repeat (int $count)

Répète la chaîne x fois.

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

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

Remplace toutes les occurrences de la chaîne de recherche par la chaîne de remplacement.

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

Il est possible d'effectuer plusieurs remplacements à la fois :

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

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

Effectue une recherche d'expressions régulières avec remplacement.

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

reverse

Inverse la chaîne ou le tableau donné.

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

round (int $precision=0)

Arrondit un nombre à la précision donnée.

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

Voir aussi ceil, floor.

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

Extrait une partie d'un tableau ou d'une chaîne.

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

Le filtre fonctionne comme la fonction PHP array_slice pour les tableaux ou mb_substr pour les chaînes avec un fallback sur la fonction iconv_substr en mode UTF‑8.

Si start est positif, la séquence commencera décalée de ce nombre depuis le début du tableau/chaîne. Si il est négatif, la séquence commencera décalée d'autant depuis la fin.

Si le paramètre length est spécifié et est positif, la séquence contiendra autant d'éléments. Si un paramètre length négatif est passé à cette fonction, la séquence contiendra tous les éléments du tableau d'origine, commençant à la position start et se terminant à la position inférieure de length éléments par rapport à la fin du tableau. Si vous ne spécifiez pas ce paramètre, la séquence contiendra tous les éléments du tableau d'origine, commençant à la position start.

Par défaut, le filtre modifie l'ordre et réinitialise les clés entières du tableau. Ce comportement peut être modifié en définissant preserveKeys sur true. Les clés de chaîne sont toujours préservées, quel que soit ce paramètre.

sort (?Closure $comparison, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false)

Le filtre trie les éléments d'un tableau ou d'un itérateur et préserve leurs clés associatives. Si les paramètres régionaux sont définis, le tri suit ses règles, sauf si une fonction de comparaison personnalisée est spécifiée.

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

Tableau trié en ordre inverse :

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

Vous pouvez spécifier une fonction de comparaison personnalisée pour le tri (l'exemple montre comment inverser le tri du plus grand au plus petit) :

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

Le filtre |sort permet également de trier les éléments par clés :

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

Si vous avez besoin de trier un tableau selon une colonne spécifique, vous pouvez utiliser le paramètre by. La valeur 'name' dans l'exemple indique que le tri se fera selon $item->name ou $item['name'], selon que $item est un tableau ou un objet :

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

Vous pouvez également définir une fonction de rappel qui déterminera la valeur selon laquelle trier :

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

Le paramètre byKey peut être utilisé de la même manière.

spaceless

Supprime les espaces blancs inutiles de la sortie. Vous pouvez également utiliser l'alias strip.

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

Affiche :

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

stripHtml

Convertit le HTML en texte brut. C'est-à-dire qu'il supprime les balises HTML et convertit les entités HTML en texte.

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

Le texte brut résultant peut naturellement contenir des caractères qui représentent des balises HTML, par exemple '<p>'|stripHtml est converti en <p>. N'affichez en aucun cas le texte ainsi obtenu avec |noescape, car cela peut entraîner une faille de sécurité.

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

Extrait une partie d'une chaîne. Ce filtre a été remplacé par le filtre slice.

{$string|substr: 1, 2}

translate (…$args)

Traduit les expressions dans d'autres langues. Pour que le filtre soit disponible, il faut configurer le traducteur. Vous pouvez également utiliser les balises de traduction.

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

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

Supprime les espaces blancs (ou autres caractères) du début et de la fin de la chaîne.

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

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

Tronque une chaîne à la longueur maximale spécifiée, en essayant de conserver les mots entiers. Si la chaîne est raccourcie, ajoute des points de suspension à la fin (peut être modifié avec le deuxième paramètre).

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

upper

Convertit une chaîne en majuscules. Nécessite l'extension PHP mbstring.

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

Voir aussi capitalize, firstUpper, lower.

webalize

Modifie une chaîne UTF‑8 dans la forme utilisée dans les URL.

Convertit en ASCII. Convertit les espaces en tirets. Supprime les caractères qui ne sont pas alphanumériques, des traits de soulignement ou des tirets. Convertit en minuscules. Supprime également les espaces de début et de fin.

{var $s = 'Notre 10ème produit'}
{$s|webalize}   {* affiche 'notre-10eme-produit' *}

Nécessite la bibliothèque nette/utils.