Filtres de Latte
****************

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

.[table-latte-filters]
|## Transformation de chaînes / tableaux
| `batch` | [Liste les données linéaires dans un tableau |#batch]
| `breakLines` | [Insère des sauts de ligne HTML avant toutes les nouvelles lignes |#breakLines]
| `bytes` | [Formate la taille en octets |#bytes]
| `clamp` | [Fixe la valeur à l'intervalle |#clamp]
| `dataStream` | [Conversion du protocole URI des données |#datastream]
| `date` | [Formate la date |#date]
| `explode` | [divise une chaîne de caractères par le délimiteur donné |#explode]
| `first` | [renvoie le premier élément d'un tableau ou le premier caractère d'une chaîne de caractères |#first]
| `implode` | [joint un tableau à une chaîne de caractères |#implode]
| `indent` | [indente le texte à partir de la gauche avec un nombre de tabulations |#indent]
| `join` | [joint un tableau à une chaîne de caractères |#implode]
| `last` | [renvoie le dernier élément d'un tableau ou le dernier caractère d'une chaîne de caractères |#last]
| `length` | [retourne la longueur d'une chaîne ou d'un tableau |#length]
| `number` | [Formate un nombre |#number]
| `padLeft` | [Complète une chaîne de caractères à une longueur donnée en partant de la gauche |#padLeft]
| `padRight` | [Complète la chaîne à la longueur donnée à partir de la droite |#padRight]
| `random` | [renvoie un élément aléatoire d'un tableau ou un caractère d'une chaîne de caractères |#random]
| `repeat` | [répète la chaîne de caractères |#repeat]
| `replace` | [remplace toutes les occurrences de la chaîne de recherche par le remplacement |#replace]
| `replaceRE` | [remplace toutes les occurrences selon l'expression régulière |#replaceRE]
| `reverse` | [inverse une chaîne ou un tableau UTF-8 |#reverse]
| `slice` | [extrait une tranche d'un tableau ou d'une chaîne de caractères |#slice]
| `sort` | [trie un tableau |#sort]
| `spaceless` | [supprime les espaces |#spaceless], similaire à la balise [spaceless |tags]
| `split` | [divise une chaîne de caractères par le délimiteur donné |#explode]
| `strip` | [supprime les espaces blancs |#spaceless]
| `stripHtml` | [supprime les balises HTML et convertit les entités HTML en texte |#stripHtml]
| `substr` | [retourne une partie de la chaîne |#substr]
| `trim` | [supprime les espaces de la chaîne de caractères |#trim]
| `translate` | [traduction dans d'autres langues |#translate]
| `truncate` | [raccourcit la longueur en préservant les mots entiers |#truncate]
| `webalize` | [ajuste la chaîne UTF-8 à la forme utilisée dans l'URL |#webalize]

.[table-latte-filters]
|## Mise en forme des lettres
| `capitalize` | [minuscule, la première lettre de chaque mot majuscule |#capitalize]
| `firstUpper` | [met la première lettre en majuscule |#firstUpper]
| `lower` | [met une chaîne de caractères en minuscule |#lower]
| `upper` | [met une chaîne de caractères en majuscule |#upper]

.[table-latte-filters]
|## Arrondir les nombres
| `ceil` | [arrondit un nombre à une précision donnée |#ceil]
| `floor` | [arrondit un nombre à une précision donnée vers le bas |#floor]
| `round` | [arrondit un nombre à une précision donnée |#round]

.[table-latte-filters]
|## Escapes
| `escapeUrl` | [échappe le paramètre dans l'URL |#escapeUrl]
| `noescape` | [imprime une variable sans échappement |#noescape]
| `query` | [génère une chaîne de requête dans l'URL |#query]

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 |safety-first#Context-aware escaping] et que vous n'avez pas besoin d'écrire.

.[table-latte-filters]
|## Sécurité
| `checkUrl` | [aseptise la chaîne de caractères à utiliser dans l'attribut href |#checkUrl]
| `nocheck` | [empêche la désinfection automatique des URLs |#nocheck]

Les [vérifications des |safety-first#link checking] attributs `src` et `href` sont [automatiques |safety-first#link checking], de sorte que vous n'avez pratiquement pas besoin d'utiliser le filtre `checkUrl`.


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


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

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

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

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

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

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

Les filtres peuvent être appliqués sur une expression :

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

Les [filtres personnalisés |extending-latte#filters] peuvent être enregistrés de cette manière :

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

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


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


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

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

Imprime :

```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]
--------------------
Insère des sauts de ligne HTML avant tous les retours à la ligne.

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


bytes(int precision = 2) .[filter]
----------------------------------
Formate une taille en octets sous une forme lisible par l'homme.

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


ceil(int precision = 0) .[filter]
---------------------------------
Arrondit un nombre à une précision donnée.

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

Voir aussi [plancher |#floor], [rond |#round].


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

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

Voir aussi [firstUpper |#firstUpper], [lower |#lower], [upper |#upper].


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

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

Imprime :

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

Voir aussi [nocheck |#nocheck].


clamp(int|float min, int|float max) .[filter]
---------------------------------------------
Renvoie une valeur limitée à l'intervalle inclusif de min et max.

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

Existe aussi en tant que [fonction |functions#clamp].


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

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

Imprime par exemple :

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

.[caution]
Nécessite l'extension PHP `fileinfo`.


date(string format) .[filter]
-----------------------------
Renvoie une date au format donné en utilisant les options des fonctions PHP [php:strftime] ou [php:date]. Le filtre permet d'obtenir une date sous la forme d'un timestamp UNIX, d'une chaîne de caractères ou d'un objet de type `DateTime`.

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


escapeUrl .[filter]
-------------------
Échappe une variable qui sera utilisée comme paramètre dans une URL.

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

Voir aussi [query |#query].


explode(string separator = '') .[filter]
----------------------------------------
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`.

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

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

Vous pouvez également utiliser l'alias `split`:

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

Voir aussi [implode |#implode].


first .[filter]
---------------
Renvoie le premier élément d'un tableau ou le premier caractère d'une chaîne de caractères :

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

Voir aussi [last |#last], [random |#random].


floor(int precision = 0) .[filter]
----------------------------------
Arrondit un nombre à une précision donnée.

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

Voir aussi [ceil |#ceil], [round |#round].


firstUpper .[filter]
--------------------
Convertit la première lettre d'une valeur en majuscule. Nécessite l'extension PHP `mbstring`.

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

Voir aussi [majuscule |#capitalize], [inférieur |#lower], [supérieur |#upper].


implode(string glue = '') .[filter]
-----------------------------------
Retourne une chaîne de caractères qui est la concaténation des chaînes de caractères du tableau. Alias pour `join`.

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

Vous pouvez également utiliser un alias `join`:

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


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

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

Imprime :

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


last .[filter]
--------------
Renvoie le dernier élément du tableau ou le dernier caractère de la chaîne de caractères :

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

Voir aussi [first |#first], [random |#random].


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


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


lower .[filter]
---------------
Convertit une valeur en minuscule. Nécessite l'extension PHP `mbstring`.

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

Voir aussi [capitalize |#capitalize], [firstUpper |#firstUpper], [upper |#upper].


nocheck .[filter]
-----------------
Empêche la désinfection automatique des URL. Latte [vérifie automatiquement |safety-first#Link checking] 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`.

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

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

Imprimés :

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

Voir aussi [checkUrl |#checkUrl].


noescape .[filter]
------------------
Désactive l'échappement automatique.

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

Imprime :

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

.[warning]
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 = ',') .[filter]
------------------------------------------------------------------------------------
Formate un nombre avec un nombre donné de décimales. Vous pouvez également spécifier un caractère du point décimal et du séparateur de milliers.

```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]
-----------------------------------------------
Remplit une chaîne de caractères d'une certaine longueur avec une autre chaîne de caractères à partir de la gauche.

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


padRight(int length, string pad = ' ') .[filter]
------------------------------------------------
Remplir une chaîne de caractères d'une certaine longueur avec une autre chaîne de caractères de droite.

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


query  .[filter]
----------------
Génère dynamiquement une chaîne de requête dans l'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>
```

Imprime :

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


random .[filter]
----------------
Renvoie un élément aléatoire du tableau ou un caractère de la chaîne :

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

Voir aussi [first |#first], [last |#last].


repeat(int count) .[filter]
---------------------------
Répète la chaîne x fois.

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


replace(string|array search, string replace = '') .[filter]
-----------------------------------------------------------
Remplace toutes les occurrences de la chaîne de recherche par la chaîne de remplacement.

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

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

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


replaceRE(string pattern, string replace = '') .[filter]
--------------------------------------------------------
Remplace toutes les occurrences selon l'expression régulière.

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


reverse .[filter]
-----------------
Inverse une chaîne ou un tableau donné.

```latte
{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) .[filter]
----------------------------------
Arrondit un nombre à une précision donnée.

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


slice(int start, int length = null, bool preserveKeys = false) .[filter]
------------------------------------------------------------------------
Extrait une tranche d'un tableau ou d'une chaîne de caractères.

```latte
{='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  .[filter]
---------------
Filtre qui trie un tableau et maintient l'association des index.

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

Tableau trié dans l'ordre inverse.

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

Vous pouvez passer votre propre fonction de comparaison en paramètre :

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


spaceless  .[filter]
--------------------
Supprime les espaces inutiles de la sortie. Vous pouvez également utiliser l'alias `strip`.

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

Imprime :

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


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

```latte
{='<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 `'&lt;p&gt;'|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) .[filter]
-----------------------------------------------
Extrait une tranche d'une chaîne de caractères. Ce filtre a été remplacé par un filtre de [tranche |#slice].

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


translate(string message, ...args) .[filter]
--------------------------------------------
Il traduit les expressions dans d'autres langues. Pour rendre ce filtre disponible, vous devez [configurer le traducteur |develop#TranslatorExtension]. Vous pouvez également utiliser les [balises pour la traduction |tags#Translation].

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


trim(string charlist = " \t\n\r\0\x0B\u{A0}") .[filter]
-------------------------------------------------------
Supprime les caractères de tête et de queue, par défaut les espaces blancs.

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


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

```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]
---------------
Convertit une valeur en majuscule. Nécessite l'extension PHP `mbstring`.

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

Voir aussi [capitalize |#capitalize], [firstUpper |#firstUpper], [lower |#lower].


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

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

.[caution]
Nécessite le paquet [nette/utils |utils:].