Étendre Latte
*************

.[perex]
Latte est conçu pour être extensible. Si son jeu standard de balises, de filtres et de fonctions couvre déjà beaucoup de cas, vous avez souvent besoin d'ajouter votre propre logique ou vos propres utilitaires. Cette page donne un aperçu des façons d'étendre Latte pour coller parfaitement aux besoins de votre projet, du simple utilitaire à la nouvelle syntaxe complexe.


Façons d'étendre Latte
======================

Voici un aperçu rapide des principaux moyens de personnaliser et d'étendre Latte :

- **[Filtres personnalisés|custom-filters] :** pour formater ou transformer des données directement dans la sortie du template (par ex. `{$var|myFilter}`). Idéal pour le formatage de dates, la manipulation de texte ou l'application d'un échappement particulier. Vous pouvez aussi vous en servir pour modifier de plus gros blocs de contenu HTML, en enveloppant le contenu dans un [`{block}` |tags#{block}] anonyme auquel vous appliquez un filtre personnalisé.
- **[Fonctions personnalisées|custom-functions] :** pour ajouter une logique réutilisable appelable dans les expressions du template (par ex. `{myFunction($arg1, $arg2)}`). Utile pour les calculs, l'accès aux utilitaires de l'application ou la génération de petits fragments de contenu.
- **[Balises personnalisées|custom-tags] :** pour créer de toutes nouvelles constructions de langage (`{mytag}...{/mytag}` ou `n:mytag`). Les balises offrent le plus de puissance : elles permettent de définir des structures propres, de contrôler l'analyse du template et d'implémenter une logique de rendu complexe.
- **[Passes de compilation|compiler-passes] :** fonctions qui modifient l'arbre syntaxique abstrait (AST) du template après l'analyse, mais avant la génération du code PHP. Elles servent aux optimisations avancées, aux contrôles de sécurité (comme le Sandbox) ou aux modifications automatiques du code.
- **[Loaders personnalisés|loaders] :** pour changer la manière dont Latte trouve et charge les fichiers de template (chargement depuis une base de données, un stockage chiffré, etc.).

Choisir la bonne méthode d'extension est essentiel. Avant de créer une balise complexe, demandez-vous si un simple filtre ou une simple fonction ne suffirait pas. Prenons un exemple : implémenter un générateur *Lorem ipsum* qui prend en argument le nombre de mots à générer.

- **Comme balise ?** `{lipsum 40}` - possible, mais les balises conviennent mieux aux structures de contrôle ou à la génération de balisage complexe. Elles ne peuvent pas être utilisées directement dans les expressions.
- **Comme filtre ?** `{=40|lipsum}` - techniquement, cela fonctionne, mais les filtres sont faits pour *transformer* une entrée. Ici, `40` est un *argument*, pas la valeur transformée. C'est sémantiquement bancal.
- **Comme fonction ?** `{lipsum(40)}` - c'est la solution la plus naturelle ! Les fonctions acceptent des arguments et retournent des valeurs, ce qui les rend parfaites au sein de n'importe quelle expression : `{var $text = lipsum(40)}`.

**Recommandation générale :** utilisez les fonctions pour le calcul et la génération, les filtres pour la transformation et les balises pour les nouvelles structures de langage ou le balisage complexe. Utilisez les passes pour manipuler l'AST et les loaders pour obtenir les templates.


Enregistrement direct
=====================

Pour les utilitaires propres à un projet ou les ajouts rapides, Latte permet d'enregistrer directement filtres et fonctions sur l'objet `Latte\Engine`.

Utilisez `addFilter()` pour enregistrer un filtre. Le premier argument de votre fonction de filtre sera la valeur placée avant la barre verticale `|`, les arguments suivants étant ceux passés après le deux-points `:`.

```php
$latte = new Latte\Engine;

// Définition du filtre (callable : fonction, méthode statique, etc.)
$myTruncate = fn(string $s, int $length = 50) => mb_substr($s, 0, $length);

// Enregistrement
$latte->addFilter('truncate', $myTruncate);

// Utilisation dans le template : {$text|truncate} ou {$text|truncate:100}
```

Utilisez `addFunction()` pour enregistrer une fonction utilisable dans les expressions du template.

```php
$latte = new Latte\Engine;

// Définition de la fonction
$isWeekend = fn(DateTimeInterface $date) => $date->format('N') >= 6;

// Enregistrement
$latte->addFunction('isWeekend', $isWeekend);

// Utilisation dans le template : {if isWeekend($myDate)}Weekend!{/if}
```

Pour plus de détails, voyez [Création de filtres personnalisés|custom-filters] et [Fonctions|custom-functions].


La méthode robuste : l'extension Latte .{toc: Latte Extension}
==============================================================

L'enregistrement direct est simple, mais la façon standard et recommandée de regrouper et de distribuer des personnalisations de Latte passe par les classes **Extension**. Une Extension sert de point de configuration central pour enregistrer plusieurs balises, filtres, fonctions, passes de compilation et bien d'autres choses.

Pourquoi utiliser les Extensions ?

- **Organisation :** elles gardent au même endroit, dans une seule classe, les personnalisations liées entre elles (balises, filtres, etc. d'une même fonctionnalité).
- **Réutilisation et partage :** vous empaquetez facilement vos extensions pour les réutiliser dans d'autres projets ou les partager avec la communauté (via Composer, par exemple).
- **Pleine puissance :** les balises personnalisées et les passes de compilation *ne peuvent être enregistrées que* via des Extensions.


Enregistrement d'une Extension
------------------------------

Une Extension s'enregistre auprès de Latte avec `addExtension()` (ou via le [fichier de configuration |application:configuration#Templates Latte]) :

```php
$latte = new Latte\Engine;
$latte->addExtension(new MyProjectExtension);
```

Si vous enregistrez plusieurs extensions et qu'elles définissent des balises, filtres ou fonctions de même nom, c'est la dernière ajoutée qui l'emporte. Cela implique aussi que vos extensions peuvent redéfinir les balises, filtres et fonctions natifs.

Chaque fois que vous modifiez une classe et que le rafraîchissement automatique n'est pas désactivé, Latte recompile automatiquement vos templates.


Création d'une Extension
------------------------

Pour créer votre propre extension, vous devez écrire une classe qui hérite de [api:Latte\Extension]. Pour vous faire une idée de ce à quoi ressemble une extension, jetez un œil à la [CoreExtension |https://github.com/nette/latte/blob/master/src/Latte/Essential/CoreExtension.php] intégrée.

Voyons les méthodes que vous pouvez implémenter :


beforeCompile(Latte\Engine $engine): void .[method]
---------------------------------------------------

Appelée avant la compilation du template. La méthode peut servir par exemple à des initialisations liées à la compilation.


getTags(): array .[method]
--------------------------

Appelée lors de la compilation du template. Retourne un tableau associatif *nom de balise => callable*, où les callables sont les fonctions d'analyse des balises. [En savoir plus|custom-tags].

```php
public function getTags(): array
{
	return [
		'foo' => FooNode::create(...),
		'bar' => BarNode::create(...),
		'n:baz' => NBazNode::create(...),
		// ...
	];
}
```

La balise `n:baz` représente un pur [n:attribut |syntax#n:attributs], c'est-à-dire une balise qui ne peut s'écrire que sous forme d'attribut.

Pour les balises `foo` et `bar`, Latte reconnaît automatiquement s'il s'agit de balises paires ; si c'est le cas, elles peuvent aussi s'écrire sous forme de n:attributs, y compris les variantes préfixées `n:inner-foo` et `n:tag-foo`.

L'ordre d'exécution de ces n:attributs est déterminé par leur ordre dans le tableau retourné par `getTags()`. Ainsi, `n:foo` s'exécute toujours avant `n:bar`, même si les attributs sont écrits dans l'ordre inverse dans la balise HTML, comme `<div n:bar="..." n:foo="...">`.

Si vous avez besoin de fixer l'ordre des n:attributs entre plusieurs extensions, utilisez la méthode utilitaire `order()`, où le paramètre `before` et/ou `after` indique quelles balises passent avant ou après la balise.

```php
public function getTags(): array
{
	return [
		'foo' => self::order(FooNode::create(...), before: 'bar'),
		'bar' => self::order(BarNode::create(...), after: ['block', 'snippet']),
	];
}
```


getPasses(): array .[method]
----------------------------

Appelée lors de la compilation du template. Retourne un tableau associatif *nom de passe => callable*, où les callables sont les fonctions représentant les [passes de compilation|compiler-passes] qui parcourent et modifient l'AST.

Là encore, la méthode utilitaire `order()` peut servir. La valeur des paramètres `before` ou `after` peut être `*`, au sens de avant/après tout le reste.

```php
public function getPasses(): array
{
	return [
		'optimize' => Passes::optimizePass(...),
		'sandbox' => self::order($this->sandboxPass(...), before: '*'),
		// ...
	];
}
```


beforeRender(Latte\Runtime\Template $template): void .[method]
--------------------------------------------------------------

Appelée avant chaque rendu de template. La méthode peut servir par exemple à initialiser les variables utilisées pendant le rendu.


afterRender(Latte\Runtime\Template $template): void .[method]{data-version:3.1.6}
---------------------------------------------------------------------------------
Appelée après chaque rendu de template. Elle s'exécute même si le rendu se termine prématurément via `{exitIf}` ou est interrompu par une exception, ce qui en fait le bon endroit pour le nettoyage ou la mesure.


getFilters(): array .[method]
-----------------------------

Appelée lorsque l'extension est enregistrée par la méthode `addExtension()`. Retourne les filtres sous forme de tableau associatif *nom de filtre => callable*. [En savoir plus|custom-filters].

```php
public function getFilters(): array
{
	return [
		'batch' => $this->batchFilter(...),
		'trim' => $this->trimFilter(...),
		// ...
	];
}
```


getFunctions(): array .[method]
-------------------------------

Appelée lorsque l'extension est enregistrée par la méthode `addExtension()`. Retourne les fonctions sous forme de tableau associatif *nom de fonction => callable*. [En savoir plus|custom-functions].

```php
public function getFunctions(): array
{
	return [
		'clamp' => $this->clampFunction(...),
		'divisibleBy' => $this->divisibleByFunction(...),
		// ...
	];
}
```


getProviders(): array .[method]
-------------------------------

Appelée lorsque l'extension est enregistrée par la méthode `addExtension()`. Retourne un tableau de providers, généralement des objets que les balises utilisent à l'exécution. On y accède via `$this->global->...`. [En savoir plus |custom-tags#Présentation des providers].

```php
public function getProviders(): array
{
	return [
		'myFoo' => $this->foo,
		'myBar' => $this->bar,
		// ...
	];
}
```


getCacheKey(Latte\Engine $engine): mixed .[method]
--------------------------------------------------

Appelée avant le rendu du template. La valeur de retour devient une partie de la clé dont le hachage figure dans le nom du fichier de template compilé. Pour des valeurs de retour différentes, Latte génère donc des fichiers de cache différents.