Filtres Latte
*************

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

.[table-latte-filters]
|## Transformation
| `batch`      | [affichage de données linéaires sous forme de tableau |#batch]
| `breakLines` | [insère des sauts de ligne HTML avant chaque fin de ligne |#breakLines]
| `bytes`      | [formate une taille en octets |#bytes]
| `clamp`      | [borne une valeur à la plage donnée |#clamp]
| `column`     | [extrait une seule colonne d'un tableau |#column]
| `commas`     | [joint un tableau avec des virgules |#commas]
| `limit`      | [limite la longueur d'un tableau, d'une chaîne ou d'un itérateur |#limit]
| `dataStream` | [conversion pour le protocole Data URI |#dataStream]
| `date`       | [formate la date et l'heure |#date]
| `explode`    | [découpe une chaîne en tableau selon un délimiteur |#explode]
| `filter`     | [filtre les éléments d'un itérable selon un prédicat |#filter]
| `first`      | [retourne le premier élément d'un tableau ou le premier caractère d'une chaîne |#first]
| `group`      | [regroupe les données selon différents critères |#group]
| `implode`    | [joint un tableau en une chaîne |#implode]
| `indent`     | [indente le texte depuis la gauche d'un nombre donné de tabulations |#indent]
| `join`       | [joint un tableau en une chaîne |#implode]
| `last`       | [retourne le dernier élément d'un tableau ou le dernier caractère d'une chaîne |#last]
| `length`     | [retourne la longueur d'une chaîne ou d'un tableau |#length]
| `localDate`  | [formate la date et l'heure selon la locale |#localDate]
| `map`        | [applique un callback à chaque élément |#map]
| `number`     | [formate un nombre |#number]
| `padLeft`    | [complète une chaîne jusqu'à une certaine longueur depuis la gauche |#padLeft]
| `padRight`   | [complète une chaîne jusqu'à une certaine longueur depuis la droite |#padRight]
| `random`     | [retourne un élément aléatoire d'un tableau ou un caractère aléatoire d'une chaîne |#random]
| `repeat`     | [répète une chaîne |#repeat]
| `replace`    | [remplace les occurrences de la chaîne recherchée |#replace]
| `replaceRE`  | [remplace les occurrences selon une expression régulière |#replaceRE]
| `reverse`    | [inverse une chaîne UTF‑8 ou un tableau |#reverse]
| `slice`      | [extrait une portion d'un tableau ou d'une chaîne |#slice]
| `sort`       | [trie un tableau |#sort]
| `spaceless`  | [supprime les espaces |#spaceless], comme la balise [spaceless |tags]
| `split`      | [découpe une chaîne en tableau selon un délimiteur |#explode]
| `strip`      | [supprime les espaces |#spaceless], alias obsolète de `spaceless`
| `stripHtml`  | [supprime les balises HTML et convertit les entités HTML en caractères |#stripHtml]
| `substr`     | [retourne une partie d'une chaîne |#substr]
| `trim`       | [supprime les espaces ou d'autres caractères en début et fin de chaîne |#trim]
| `translate`  | [traduction dans d'autres langues |#translate]
| `truncate`   | [raccourcit la longueur en préservant les mots entiers |#truncate]
| `webalize`   | [adapte une chaîne UTF‑8 à la forme utilisée dans les URL |#webalize]

.[table-latte-filters]
|## Casse des lettres
| `capitalize` | [minuscules, première lettre de chaque mot en majuscule |#capitalize]
| `firstLower` | [convertit la première lettre en minuscule |#firstLower]
| `firstUpper` | [convertit la première lettre en majuscule |#firstUpper]
| `lower`      | [convertit en minuscules |#lower]
| `upper`      | [convertit en majuscules |#upper]

.[table-latte-filters]
|## Arrondi
| `ceil`       | [arrondit un nombre vers le haut à la précision donnée |#ceil]
| `floor`      | [arrondit un nombre vers le bas à la précision donnée |#floor]
| `round`      | [arrondit un nombre à la précision donnée |#round]

.[table-latte-filters]
|## Attributs HTML
| `accept`     | [accepte le nouveau comportement des attributs intelligents |#accept]
| `toggle`     | [bascule la présence d'un attribut HTML |#toggle]

.[table-latte-filters]
|## Échappement
| `escapeUrl`  | [échappe un paramètre dans une URL |#escapeUrl]
| `noescape`   | [affiche une variable sans échappement |#noescape]
| `query`      | [génère une chaîne de requête dans une 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 sensible au contexte |safety-first#Échappement contextuel] et que vous n'avez pas besoin d'écrire.

.[table-latte-filters]
|## Sécurité
| `checkUrl`   | [nettoie une adresse URL des entrées dangereuses |#checkUrl]
| `nocheck`    | [empêche le nettoyage automatique de l'URL |#nocheck]

Latte [vérifie automatiquement |safety-first#Vérification des liens] les attributs `src` et `href`, si bien que vous n'avez presque jamais besoin du filtre `checkUrl`.


.[note]
Tous les filtres intégrés sont conçus pour des chaînes encodées en UTF‑8.


Utilisation
===========

Les filtres s'écrivent après la barre verticale (un espace peut la précéder) :

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

Les filtres peuvent s'enchaîner et s'appliquent alors de gauche à droite :

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

Les paramètres se saisissent 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 aussi s'appliquer à une expression :

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

Les [filtres personnalisés|custom-filters] s'enregistrent de cette manière :

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

On les appelle ensuite ainsi dans le template :

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


Filtres nullsafe .{data-version:3.1.0}
--------------------------------------

N'importe quel filtre peut devenir nullsafe en utilisant `?|` au lieu de `|`. Si la valeur vaut `null`, le filtre n'est pas exécuté et `null` est retourné. Les filtres suivants de la chaîne sont eux aussi ignorés.

C'est utile en combinaison avec les attributs HTML, qui sont omis lorsque la valeur vaut `null`.

```latte
<div title={$title?|upper}>
{* Si $title vaut null : <div> *}
{* Si $title vaut 'hello' : <div title="HELLO"> *}
```


Filtres
=======


accept .[filter]{data-version:3.1.0}
------------------------------------
Ce filtre s'utilise lors de la [migration depuis Latte 3.0|cookbook/migration-from-latte-30] pour confirmer que vous avez examiné le changement de comportement des attributs et que vous l'acceptez. Il ne modifie pas la valeur.

C'est un outil temporaire. Une fois la migration terminée et les avertissements de migration désactivés, vous devriez retirer ce filtre de vos templates.


batch(int $length, mixed $rest=null): Generator .[filter]
---------------------------------------------------------
Filtre qui simplifie l'affichage de données linéaires sous forme de tableau. Il retourne un générateur de tableaux comportant le nombre d'éléments indiqué. Si vous fournissez un second paramètre, il servira à compléter les éléments manquants de 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>
```

Affiche :

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

Voir aussi [#group] et la balise [iterateWhile |tags#{iterateWhile}].


breakLines .[filter]
--------------------
Insère une balise HTML `<br>` avant chaque caractère de fin de ligne.

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


bytes(int $precision=2) .[filter]
---------------------------------
Formate une taille en octets sous une forme lisible. Si la [locale |develop#Locale] est définie, les séparateurs décimal et de milliers correspondants sont utilisés.

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


ceil(int $precision=0) .[filter]
--------------------------------
Arrondit un nombre vers le haut à la précision donnée.

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

Voir aussi [#floor], [#round].


capitalize .[filter]
--------------------
Les mots commenceront par une majuscule, tous les autres caractères seront en minuscules. Nécessite l'extension PHP `mbstring`.

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

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


checkUrl .[filter]
------------------
Force le nettoyage d'une URL. Il vérifie que l'URL utilise un schéma sûr (`http`, `https`, `ftp`, `mailto`, `tel`, `sms`) ou qu'il s'agit d'un lien relatif, et bloque les schémas dangereux comme `javascript:`, qui pourraient poser un risque de sécurité.

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

Affiche :

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

Voir aussi [#nocheck].


clamp(int|float $min, int|float $max) .[filter]
-----------------------------------------------
Borne une valeur à la plage inclusive délimitée par min et max.

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

Existe aussi comme [fonction |functions#clamp()].


column(string|int|null $columnKey, string|int|null $indexKey=null) .[filter]{data-version:3.1.3}
------------------------------------------------------------------------------------------------
Retourne, sous forme de nouveau tableau, les valeurs de la seule colonne `$columnKey` d'un tableau multidimensionnel. S'utilise aussi sur des tableaux d'objets pour extraire les valeurs de propriétés.

```latte
{var $users = [
	[id: 30, name: 'John', age: 30],
	[id: 32, name: 'Jane', age: 25],
	[id: 33, age: 35],
]}

{$users|column: 'name'}
{* retourne ['John', 'Jane'] *}

{$users|column: 'name', 'id'}
{* retourne [30 => 'John', 32 => 'Jane'] *}
```

Si vous passez `null` comme clé de colonne, le tableau sera réindexé selon `$indexKey`.


commas(?string $lastGlue=null) .[filter]{data-version:3.1.3}
------------------------------------------------------------
Joint les éléments d'un tableau par une virgule suivie d'une espace (`', '`). Un raccourci pratique pour énumérer des éléments de façon lisible.

```latte
{var $items = ['apples', 'oranges', 'bananas']}
{$items|commas}
{* affiche 'apples, oranges, bananas' *}
```

Vous pouvez aussi indiquer un séparateur propre à la dernière paire d'éléments :

```latte
{$items|commas: ' and '}
{* affiche 'apples, oranges and bananas' *}

{=['PHP', 'JavaScript', 'Python']|commas: ', or '}
{* affiche 'PHP, JavaScript, or Python' *}
```

Voir aussi [#implode].


dataStream(?string $type=null) .[filter]
----------------------------------------
Convertit un contenu au format data URI. Cela permet d'intégrer des images dans du HTML ou du CSS sans lier de fichiers externes. Si `$type` vaut `null`, le type MIME est détecté automatiquement.

Soit une image dans la variable `$img = Image::fromFile('image.gif')` ; alors

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

Affiche par exemple :

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

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


date(string $format='j. n. Y') .[filter]
----------------------------------------
Formate une date et une heure selon le masque utilisé par la fonction PHP [php:date]. Le filtre accepte la date sous forme de timestamp UNIX, de chaîne, d'objet `DateTimeInterface` ou `DateInterval`.

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

Voir aussi [#localDate].


escapeUrl .[filter]
-------------------
Échappe une variable pour l'utiliser comme paramètre dans une URL.

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

Voir aussi [#query].


explode(string $separator='') .[filter]
---------------------------------------
Découpe une chaîne en tableau selon un délimiteur. Alias de `split`.

```latte
{='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 découpée en caractères individuels :

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

Vous pouvez aussi utiliser l'alias `split` :

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

Voir aussi [#implode].


filter(callable $predicate): iterable .[filter]{data-version:3.0.20}
--------------------------------------------------------------------
Filtre les éléments d'un tableau ou d'un itérateur en ne gardant que ceux pour lesquels le prédicat retourne `true`. Les clés sont préservées.

```latte
{foreach ($people|filter: fn($person) => $person->age >= 18) as $adult}
	<p>{$adult->name}</p>
{/foreach}
```


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

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

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


floor(int $precision=0) .[filter]
---------------------------------
Arrondit un nombre vers le bas à la précision donnée.

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

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


firstLower .[filter]{data-version:3.0.22}
-----------------------------------------
Convertit la première lettre en minuscule. Nécessite l'extension PHP `mbstring`.

```latte
{='The Latte'|firstLower}  {* affiche 'the Latte' *}
```

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


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

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

Voir aussi [#capitalize], [#firstLower], [#lower], [#upper].


group(string|int|\Closure $by): iterable .[filter]{data-version:3.0.16}
-----------------------------------------------------------------------
Ce 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 une structure itérable de groupes, dont la clé est la valeur de la colonne `categoryId`. [Lisez le guide détaillé|cookbook/grouping].

```latte
{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 |functions#group()] et la balise [iterateWhile |tags#{iterateWhile}].


implode(string $glue='') .[filter]
----------------------------------
Retourne une chaîne formée par la concaténation des éléments de la séquence. Alias de `join`.

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

Vous pouvez aussi utiliser l'alias `join` :

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

Voir aussi [#commas], [#explode].


indent(int $level=1, string $chars="\t") .[filter]
--------------------------------------------------
Indente le texte depuis la gauche d'un nombre donné de tabulations ou d'autres caractères précisés en second argument. Les lignes vides ne sont pas indentées.

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

Affiche :

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


last .[filter]
--------------
Retourne le dernier élément d'un tableau ou le dernier caractère d'une chaîne :

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

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


length .[filter]
----------------
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 implémentant l'interface Countable, utilise la valeur de retour de la méthode `count()`
- pour les objets implémentant l'interface Traversable, utilise la valeur de retour de la fonction `iterator_count()`


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


localDate(?string $format=null, ?string $date=null, ?string $time=null) .[filter]
---------------------------------------------------------------------------------
Formate la date et l'heure selon la [locale |develop#Locale], garantissant un affichage cohérent et localisé des données temporelles dans les différentes langues et régions. Le filtre accepte la date sous forme de timestamp UNIX, de chaîne ou d'objet `DateTimeInterface`.

```latte
{$date|localDate}                  {* 15 avril 2024 *}
{$date|localDate: format: yM}      {* 4/2024 *}
{$date|localDate: date: medium}    {* 15 avr. 2024 *}
```

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

**a) Utilisation d'un format**

Le paramètre `format` décrit quels composants temporels doivent être affichés. Il utilise des codes de lettres, dont le nombre de répétitions influe sur la largeur de la sortie :

| Année | `y` / `yy` / `yyyy` | `2024` / `24` / `2024`
| Mois | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `Aug` / `August`
| Jour | `d` / `dd` / `E` / `EEEE` |  `1` / `01` / `Sun` / `Sunday`
| Heure | `j` /  `H` / `h` | préférée / 24 heures / 12 heures
| Minute | `m` / `mm` | `5` / `05` <small>(2 chiffres en combinaison avec les secondes)</small>
| Seconde | `s` / `ss` | `8` / `08` <small>(2 chiffres en combinaison avec les minutes)</small>

L'ordre des codes dans le format n'a pas d'importance, car l'ordre des composants suivra les conventions de la locale. Le format est donc indépendant de la locale. Ainsi, le format `yyyyMMMMd` affiche `April 15, 2024` dans la locale `en_US`, tandis qu'en `cs_CZ` il donne `15. dubna 2024` :

| locale : | cs_CZ | en_US
|---
| `format: 'dMy'` | 10. 8. 2024 | 8/10/2024
| `format: 'yM'` | 8/2024 | 8/2024
| `format: 'yyyyMMMM'` | srpen 2024 | August 2024
| `format: 'MMMM'` | srpen | August
| `format: 'jm'` | 17:22 | 5:22 PM
| `format: 'Hm'` | 17:22 | 17:22
| `format: 'hm'` | 5:22 odp. | 5:22 PM


**b) Utilisation de styles prédéfinis**

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

| locale : | cs_CZ | en_US
|---
| `date: short` | 23.01.78 | 1/23/78
| `date: medium` | 23. 1. 1978 | Jan 23, 1978
| `date: long` | 23. ledna 1978 | January 23, 1978
| `date: full` | pondělí 23. ledna 1978 | Monday, January 23, 1978
| `time: short` | 8:30 | 8:30 AM
| `time: medium` | 8:30:59 | 8:30:59 AM
| `time: long` | 8:30:59 SEČ | 8:30:59 AM GMT+1
| `date: short, time: short` | 23.01.78 8:30 | 1/23/78, 8:30 AM
| `date: medium, time: short` | 23. 1. 1978 8:30 | Jan 23, 1978, 8:30 AM
| `date: long, time: short` | 23. ledna 1978 v 8:30 | January 23, 1978 at 8:30 AM

Pour la date, vous pouvez en outre utiliser le préfixe `relative-` (par ex. `relative-short`), qui affiche `hier`, `aujourd'hui` ou `demain` pour les dates proches du présent, et s'en tient sinon à l'affichage standard.

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

Voir aussi [#date].


lower .[filter]
---------------
Convertit une chaîne en minuscules. Nécessite l'extension PHP `mbstring`.

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

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


map(callable $transformer): iterable .[filter]{data-version:3.1.6}
------------------------------------------------------------------
Transforme chaque élément d'un tableau ou d'un itérateur à l'aide d'un callback et retourne un nouvel itérateur. C'est le pendant du filtre [#filter]. Les clés sont préservées.

```latte
{=($users|map: fn($user) => $user->name)|implode: ', '}   {* John, Mary, Paul *}
```

Voir aussi [#filter].


nocheck .[filter]
-----------------
Empêche le nettoyage automatique de l'URL. Latte [vérifie automatiquement |safety-first#Vérification des liens] qu'une URL utilise un schéma sûr (comme `http`, `https`, `ftp`, `mailto`, `tel`, `sms`) ou qu'il s'agit d'un lien relatif, et bloque les schémas potentiellement dangereux.

Si le lien utilise un autre schéma, comme `javascript:` ou `data:`, et que vous êtes certain de son contenu, vous pouvez désactiver la vérification avec `|nocheck`.

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

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

Affiche :

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

Voir aussi [#checkUrl].


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

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

Affiche :

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

.[warning]
Un mauvais usage du filtre `noescape` peut ouvrir une vulnérabilité XSS ! Ne l'utilisez jamais sans être **absolument certain** de ce que vous faites et que la chaîne affichée provient d'une source de confiance.


number(int $decimals=0, string $decPoint='.', string $thousandsSep=',') .[filter]
---------------------------------------------------------------------------------
Formate un nombre avec un nombre de décimales donné. Si la [locale |develop#Locale] est définie, les séparateurs décimal et de milliers correspondants sont utilisés.

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


number(string $format) .[filter]
--------------------------------
Le paramètre `format` vous permet de définir l'apparence des nombres exactement selon vos besoins. Cela nécessite que la [locale |develop#Locale] soit définie. Le format se compose de plusieurs caractères spéciaux, dont la documentation "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns donne la description complète :

- `0` chiffre obligatoire, toujours affiché même s'il vaut zéro
- `#` chiffre facultatif, affiché seulement si le nombre a effectivement un chiffre à cette place
- `@` chiffre significatif, aide à afficher le nombre avec un certain nombre de chiffres significatifs
- `.` indique où doit se trouver le séparateur décimal (point ou virgule, selon le pays)
- `,` sert à séparer les groupes de chiffres, le plus souvent les milliers
- `%` multiplie le nombre par 100 et ajoute le signe pourcent

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

```latte
{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, avec arrondi si nécessaire :

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

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

Nous pouvons définir un format différent pour les nombres positifs et négatifs, séparés par un caractère `;`. Les nombres positifs peuvent ainsi être affichés avec un signe `+` :

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

N'oubliez pas que l'apparence réelle des nombres peut varier selon les réglages du pays. Dans certains pays, par exemple, la virgule sert de séparateur décimal à la place du point. Ce filtre en tient compte automatiquement, vous n'avez donc pas à vous en soucier.


padLeft(int $length, string $append=' ') .[filter]
--------------------------------------------------
Complète une chaîne ou un nombre jusqu'à une certaine longueur avec une autre chaîne, depuis la gauche.

```latte
{='hello'|padLeft: 10, '123'}  {* affiche '12312hello' *}
{=123|padLeft: 5, '0'}         {* affiche '00123' *}
```


padRight(int $length, string $append=' ') .[filter]
---------------------------------------------------
Complète une chaîne ou un nombre jusqu'à une certaine longueur avec une autre chaîne, depuis la droite.

```latte
{='hello'|padRight: 10, '123'}  {* affiche 'hello12312' *}
{=123|padRight: 5, '0'}         {* affiche '12300' *}
```


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

Affiche :

```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 clés dont la valeur est `null` sont omises.

Voir aussi [#escapeUrl].


random .[filter]
----------------
Retourne un élément aléatoire d'un tableau ou un caractère aléatoire d'une chaîne :

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

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


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

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


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

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

Plusieurs remplacements peuvent se faire d'un coup :

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


replaceRE(string $pattern, string $replacement='') .[filter]
------------------------------------------------------------
Effectue une recherche et un remplacement par expression régulière.

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


reverse(bool $preserveKeys=false) .[filter]
-------------------------------------------
Inverse la chaîne ou le tableau donné.

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

```latte
{=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) .[filter]
------------------------------------------------------------------------
Extrait une portion d'un tableau, d'une chaîne ou d'un itérateur.

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

Le filtre se comporte comme la fonction PHP `array_slice` pour les tableaux ou `mb_substr` pour les chaînes. Pour les itérateurs, il retourne un générateur : les éléments sont consommés un à un depuis la source et la lecture s'arrête dès la limite atteinte. L'itérateur entier n'est jamais chargé en mémoire.

Si `start` est positif ou nul, la séquence commencera à ce décalage depuis le début du tableau ou de la chaîne. Si `start` est négatif, elle commencera à cette distance de la fin.

Si `length` est indiqué et positif, la séquence comptera au plus autant d'éléments. Si l'entrée est plus courte que `length`, seuls les éléments disponibles seront présents. Si `length` est indiqué et négatif, la séquence s'arrêtera à autant d'éléments de la fin de l'entrée. S'il est omis, la séquence contiendra tout, de `start` jusqu'à la fin de l'entrée.

Par défaut, le filtre réorganise et réinitialise les clés entières du tableau. Ce comportement peut être modifié en fixant `preserveKeys` à true. Les clés de type chaîne sont toujours préservées, quel que soit ce paramètre.

Voir aussi [#limit].


limit(int $length) .[filter]{data-version:3.1.3}
------------------------------------------------
Limite la longueur d'un tableau, d'une chaîne ou d'un itérateur. Pour les tableaux et les itérateurs, les clés sont préservées. Pour les chaînes, l'UTF-8 est respecté.

```latte
{foreach ($items|limit: 5) as $item}
	...
{/foreach}

{$text|limit: 100}
```


sort(?Closure $comparison=null, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false) .[filter]
-------------------------------------------------------------------------------------------------------------------
Ce filtre trie les éléments d'un tableau ou d'un itérateur en conservant leurs clés associatives. Quand une [locale |develop#Locale] est définie, le tri suit ses règles, sauf si une fonction de comparaison personnalisée est indiquée.

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

Tableau trié dans l'ordre inverse :

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

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

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

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

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

Si vous devez trier un tableau par une colonne précise, utilisez le paramètre `by`. La valeur `'name'` de l'exemple indique que le tri se fera par `$item->name` ou `$item['name']`, selon que `$item` est un tableau ou un objet :

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

Vous pouvez aussi définir une fonction de rappel qui détermine la valeur servant au tri :

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

Le paramètre `byKey` s'utilise de la même façon.


spaceless .[filter]
-------------------
Supprime les espaces superflus de la sortie. Vous pouvez aussi utiliser l'alias obsolète `strip`, mais `spaceless` est préférable.

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

Affiche :

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


stripHtml .[filter]
-------------------
Convertit du HTML en texte brut. Autrement dit, il supprime les balises HTML et convertit les entités HTML en caractères textuels.

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

Le texte brut obtenu peut naturellement contenir des caractères représentant des balises HTML : `'&lt;p&gt;'|stripHtml` donne par exemple `<p>`. N'affichez jamais le texte obtenu avec `|noescape`, cela pourrait ouvrir une faille de sécurité.


substr(int $start, ?int $length=null) .[filter]
-----------------------------------------------
Extrait une portion de chaîne. Ce filtre a été remplacé par le filtre [#slice].

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


toggle .[filter]{data-version:3.1.0}
------------------------------------
Le filtre `toggle` pilote la présence d'un attribut selon une valeur booléenne. Si la valeur est vraie, l'attribut est présent ; si elle est fausse, l'attribut est entièrement omis :

```latte
<div uk-grid={$isGrid|toggle}>
{* Si $isGrid est vrai : <div uk-grid> *}
{* Si $isGrid est faux : <div> *}
```

Ce filtre est utile pour les attributs personnalisés ou les attributs de bibliothèques JavaScript qui demandent un contrôle de présence/absence semblable à celui des attributs booléens HTML.

Le filtre ne peut s'utiliser qu'à l'intérieur d'attributs HTML.


translate(...$args) .[filter]
-----------------------------
Traduit des expressions dans d'autres langues. Pour rendre le filtre disponible, vous devez [configurer le traducteur |develop#TranslatorExtension]. Vous pouvez aussi utiliser les [balises de traduction |tags#Traduction].

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


trim(string $charlist=" \t\n\r\0\x0B\u{A0}") .[filter]
------------------------------------------------------
Supprime les espaces (ou d'autres caractères) au début et à la fin d'une chaîne.

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


truncate(int $length, string $append='…') .[filter]
---------------------------------------------------
Tronque une chaîne à la longueur maximale indiquée, en essayant de préserver les mots entiers. Si la chaîne est raccourcie, il ajoute des points de suspension à la fin (modifiable 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 chaîne en majuscules. Nécessite l'extension PHP `mbstring`.

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

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


webalize .[filter]
------------------
Adapte une chaîne UTF‑8 à la forme utilisée dans les URL.

Convertit en ASCII. Convertit les espaces en traits d'union. Supprime les caractères qui ne sont ni alphanumériques, ni des tirets bas, ni des traits d'union. Convertit en minuscules. Supprime aussi les espaces en début et fin de chaîne.

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

.[caution]
Nécessite la bibliothèque [nette/utils|utils:].