Filtres de Latte

Les filtres sont des fonctions qui modifient ou formatent les données selon nos souhaits. Voici un résumé des filtres intégrés disponibles.

Il existe également 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 vérifications des attributs src et href sont automatiques, de sorte que vous n'avez pratiquement pas besoin d'utiliser le filtre checkUrl.

Tous les filtres intégrés fonctionnent avec des chaînes encodées en UTF-8.

Utilisation

Latte permet d'appeler des filtres en utilisant la notation du signe pipe (l'espace précédent est autorisé) :

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

Les filtres peuvent être enchaînés, dans ce cas ils s'appliquent dans l'ordre de gauche à droite :

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

Les paramètres sont placé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 être appliqués sur 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));

Nous l'utilisons dans un modèle comme celui-ci :

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

Filtres

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

Filtre qui simplifie l'énumération de données linéaires sous la forme d'un tableau. Il retourne un tableau de tableaux avec le nombre d'éléments donné. Si vous fournissez un second paramètre, celui-ci est utilisé pour remplir 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>

Imprime :

<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 groupe et balise iterateWhile.

breakLines

Insère des sauts de ligne HTML avant tous les retours à la ligne.

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

bytes (int $precision=2)

Formate la taille en octets sous une forme lisible par l'homme. Si la langue locale est définie, 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 à une précision donnée.

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

Voir aussi plancher, rond.

capitalize

Renvoie une version en capitales de la valeur. Les mots commencent par des majuscules, tous les autres caractères sont en minuscules. Nécessite l'extension PHP mbstring.

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

Voir aussi firstUpper, lower, upper.

checkUrl

Assure la désinfection des URL. Il vérifie si la variable contient une URL web (c'est-à-dire un protocole HTTP/HTTPS) et empêche l'écriture de liens qui peuvent présenter un risque pour la sécurité.

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

Imprime :

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

Voir aussi nocheck.

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

Renvoie une valeur limitée à l'intervalle inclusif de min et max.

{$level|clamp: 0, 255}

Existe aussi en tant que fonction.

dataStream (string $mimetype=detect)

Convertit le contenu en schéma URI de données. Il peut être utilisé pour insérer des images dans le HTML ou le CSS sans avoir besoin de lier des fichiers externes.

Si nous avons une image dans une variable $img = Image::fromFile('obrazek.gif'), alors

<img src={$img|dataStream}>

Imprime 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, sous forme de chaîne de caractères ou d'objet DateTimeInterface.

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

Voir aussi localDate.

escapeUrl

Échappe une variable qui sera utilisée comme paramètre dans une URL.

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

Voir aussi query.

explode (string $separator='')

Divise une chaîne de caractères par le délimiteur donné et renvoie un tableau de chaînes de caractères. Alias pour split.

{='one,two,three'|explode:','}    {* returns ['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}                  {* returns ['1', '2', '3'] *}

Vous pouvez également utiliser l'alias split:

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

Voir aussi implode.

first

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

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

Voir aussi last, random.

floor (int $precision=0)

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

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

Voir aussi ceil, round.

firstUpper

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

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

Voir aussi majuscule, inférieur, supérieur.

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. Le résultat est un tableau de tableaux dont la clé est la valeur de la colonne categoryId. Lisez les instructions détaillées.

{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 de caractères qui est la concaténation des chaînes de caractères du tableau. Alias pour join.

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

Vous pouvez également utiliser un alias join:

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

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

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

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

Imprime :

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

last

Renvoie le dernier élément du tableau ou le dernier caractère de la chaîne de caractères :

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

Voir aussi first, random.

length

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

• pour les chaînes, elle renvoie la longueur en caractères UTF-8
• pour les tableaux, elle renvoie le nombre d'éléments.
• pour les objets qui implémentent l'interface Countable, elle utilisera la valeur de retour de la fonction count()
• pour les objets qui implémentent l'interface IteratorAggregate, il utilisera 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 en fonction de la locale, ce qui garantit un affichage cohérent et localisé des données temporelles dans différentes langues et régions. Le filtre accepte la date sous forme d'horodatage UNIX, de chaîne de caractères ou d'objet DateTimeInterface.

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

Si vous utilisez le filtre sans aucun paramètre, il affichera la date au niveau du format long, comme expliqué plus loin.

a) Utilisation du format

Le paramètre format décrit les composantes de l'heure qui doivent être affichées. Il utilise des codes de lettres, dont le nombre de répétitions affecte 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 locales. Le format est donc indépendant de la locale. Par exemple, le format yyyyMMMMd dans la locale en_US produit April 15, 2024, alors que dans la locale cs_CZ il produit 15. dubna 2024:

b) Utilisation de styles prédéfinis

Les paramètres date et time déterminent le niveau de détail de l'affichage de la date et de l'heure. Vous avez le choix entre plusieurs niveaux : full, long, medium, short. Vous pouvez afficher uniquement la date, uniquement l'heure ou les deux :

Pour la date, vous pouvez également utiliser le préfixe relative- (par exemple, relative-short), qui affichera yesterday, today ou tomorrow pour les dates proches de la date actuelle ; sinon, l'affichage se fera de manière standard.

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

Voir aussi date.

lower

Convertit une valeur en minuscule. Nécessite l'extension PHP mbstring.

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

Voir aussi capitalize, firstUpper, upper.

nocheck

Empêche la désinfection automatique des URL. Latte vérifie automatiquement si la variable contient une URL web (c'est-à-dire un protocole HTTP/HTTPS) et empêche l'écriture de liens pouvant présenter un risque pour la sécurité.

Si le lien utilise un schéma différent, tel que javascript: ou data:, et que vous êtes sûr de son contenu, vous pouvez désactiver la vérification via |nocheck.

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

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

Imprimés :

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

Voir aussi checkUrl.

noescape

Désactive l'échappement automatique.

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

Imprime :

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

Une mauvaise utilisation du filtre noescape peut conduire à une vulnérabilité XSS ! Ne l'utilisez jamais sans être absolument sûr de ce que vous faites et que la chaîne que vous imprimez provient d'une source fiable.

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

Formate un nombre avec le nombre de décimales spécifié. Si la locale est définie, les séparateurs de décimales 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 vous permet de définir l'apparence des chiffres exactement selon vos besoins. Il nécessite une locale définie. Le format se compose de plusieurs caractères spéciaux, dont la description complète se trouve dans la documentation “DecimalFormat” ::https://unicode.org/…numbers.html#…

• <c id=6/> chiffre obligatoire, toujours affiché même s'il est nul
• # chiffre optionnel, affiché seulement si le nombre a un chiffre à cette place
• @ chiffre significatif, permet d'afficher le nombre avec un certain nombre de chiffres significatifs
• . marque l'emplacement du séparateur décimal (virgule ou point, selon la langue)
• , utilisé pour séparer des groupes de chiffres, généralement des milliers
• % multiplie le nombre par 100 et ajoute le signe de pourcentage

Voyons quelques exemples. Dans le premier exemple, deux décimales sont obligatoires ; dans le deuxième, elles sont facultatives. Le troisième exemple montre un remplissage avec des zéros des deux côtés, et 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 le nombre de chiffres à afficher, indépendamment de la virgule, en arrondissant le nombre si nécessaire :

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

Une façon simple 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 ;. Ainsi, par exemple, les nombres positifs peuvent ê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 locaux. Par exemple, dans certains pays, une virgule est utilisée à la place d'un point comme séparateur décimal. Ce filtre en tient compte automatiquement, vous n'avez donc pas à vous en préoccuper.

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

Remplit une chaîne de caractères d'une certaine longueur avec une autre chaîne de caractères à partir de la gauche.

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

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

Remplir une chaîne de caractères d'une certaine longueur avec une autre chaîne de caractères de droite.

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

query

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

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

Imprime :

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

Les touches dont la valeur est null sont omises.

Voir également escapeUrl.

random

Renvoie un élément aléatoire du tableau ou un caractère de la chaîne :

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

Voir aussi first, last.

repeat (int $count)

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

{='hello'|repeat: 3}  {* outputs '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'}  {* outputs 'hello friend' *}

Plusieurs remplacements peuvent être effectués en même temps :

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

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

Remplace toutes les occurrences selon l'expression régulière.

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

reverse

Inverse une chaîne ou un tableau donné.

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

round (int $precision=0)

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

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

Voir aussi ceil, floor.

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

Extrait une tranche d'un tableau ou d'une chaîne de caractères.

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

Le filtre de tranche fonctionne comme la fonction PHP array_slice pour les tableaux et mb_substr pour les chaînes de caractères, avec un retour à iconv_substr en mode UTF-8.

Si start est non négatif, la séquence commencera à ce point de départ dans la variable. Si start est négatif, la séquence commencera à cette distance de la fin de la variable.

Si length est donné et est positif, alors la séquence aura jusqu'à ce nombre d'éléments. Si la variable est plus courte que la longueur, seuls les éléments disponibles de la variable seront présents. Si la longueur est donnée et qu'elle est négative, la séquence s'arrêtera à ce nombre d'éléments à partir de la fin de la variable. Si elle est omise, alors la séquence contiendra tous les éléments depuis le décalage jusqu'à la fin de la variable.

Filter réordonnera et réinitialisera les clés du tableau d'entiers par défaut. Ce comportement peut être modifié en définissant preserveKeys à true. Les clés des chaînes de caractères 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 tout en préservant leurs clés associatives. Lorsqu'une locale est définie, le tri suit ses règles à moins qu'une fonction de comparaison personnalisée ne soit spécifiée.

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

Tableau trié dans l'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 vous permet également de trier les éléments par clé :

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

Si vous devez trier un tableau en fonction d'une colonne spécifique, vous pouvez utiliser le paramètre by. La valeur 'name' dans l'exemple spécifie que le tri sera effectué par $row->name ou $row['name']selon que $row 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étermine la valeur à 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 inutiles de la sortie. Vous pouvez également utiliser l'alias strip.

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

Imprime :

<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}  {* sorties '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'éditez jamais le texte résultant avec |noescape, car cela pourrait entraîner une faille de sécurité.

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

Extrait une tranche d'une chaîne de caractères. Ce filtre a été remplacé par un filtre de tranche.

{$string|substr: 1, 2}

translate (string $message, …$args)

Il traduit les expressions dans d'autres langues. Pour rendre ce filtre disponible, vous devez configurer le traducteur. Vous pouvez également utiliser les balises pour la traduction.

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

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

Supprime les caractères de tête et de queue, par défaut les espaces blancs.

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

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

Raccourcit une chaîne de caractères à la longueur maximale donnée mais essaie de préserver les mots entiers. Si la chaîne est tronquée, elle ajoute des points de suspension à la fin (ceci peut être modifié par le second 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 valeur en majuscule. Nécessite l'extension PHP mbstring.

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

Voir aussi capitalize, firstUpper, lower.

webalize

Convertit en ASCII.

Convertit les espaces en traits d'union. Supprime les caractères qui ne sont pas des caractères alphanumériques, des traits de soulignement ou des traits d'union. Convertit en minuscules. Supprime également les espaces avant et arrière.

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

Nécessite le paquet nette/utils.