hook

La fonction hook() permet d'insérer un point d'extension dans un template Twig. Elle ne rend rien par défaut — c'est un contrôleur (via l'attribut #[Hook]) qui peut s'y accrocher pour injecter du contenu et un template alternatif.

Utilisation

{{ hook(hookName, template?, args?) }}

Exemple minimal

views/index.html.twig

{{ hook('before.about') }}
{{ component('front-page/about', about) }}
{{ hook('after.about') }}

Sans aucun contrôleur attaché, ces deux appels retournent une chaîne vide et n'affichent rien. Dès qu'un #[Hook] est enregistré, le contenu correspondant est injecté.

Paramètres

Paramètre	Type	Défaut	Description
hookName	string	—	Requis. Nom du hook. Les / sont convertis en . (front-page/services → front-page.services).
template	string	""	Optionnel. Template Twig par défaut si aucun contrôleur n'est attaché.
args	array	[]	Optionnel. Variables à injecter dans le contexte du template rendu.

Comportement détaillé

1. hook() enregistre le hook dans le service twig.hook avec le template et les args fournis.
2. Le service déclenche apply_filters('elm.<hookName>', { template, args }).
3. Si un #[Hook] est enregistré, il remplace le template et enrichit les args.
4. Si le template final est vide (aucun #[Hook] et pas de template par défaut), la fonction retourne '' silencieusement.
5. Sinon, le template est rendu par Twig avec les variables résultantes.

{{ hook('front-page.services') }}
        │
        ▼
  twig.hook::register('front-page.services', '', [])
        │
        ▼
  apply_filters('elm.front-page.services', { template: '', args: [] })
        │
        ├── Aucun #[Hook] attaché → retourne ''  (silencieux)
        │
        └── #[Hook] attaché → { template: '@child/services.html.twig', args: {…} }
                                        │
                                        ▼
                              twig->render('@child/services.html.twig', args)

Exemples d'utilisation

Point d'extension avant/après un composant

{{ hook('before.hero') }}
{{ component('front-page/hero') }}
{{ hook('after.hero') }}

Avec un template et des données par défaut

Si aucun #[Hook] n'est attaché mais que vous voulez un rendu par défaut :

{{ hook('sidebar.cta', '@theme/components/default-cta.html.twig', { label: 'En savoir plus' }) }}

Surcharger depuis un contrôleur

app/Controller/HooksController.php

use Elementum\Attributes\Hook;

class HooksController extends Controller
{
    #[Hook('sidebar.cta', '@child/cta-custom.html.twig')]
    public function ctaCustom(array $args): array
    {
        return [
            ...$args,
            'label' => 'Découvrir notre offre',
            'url'   => '/offre',
        ];
    }
}

Fonctionnement interne — Service twig.hook

Le service twig.hook (Elementum\Services\Twig\Hook) est le moteur qui coordonne les hooks Twig. Il est enregistré dans le kernel sous le nom twig.hook.

API du service

Méthode	Description
register(name, template, args): array	Enregistre un hook et applique les filtres WordPress. Retourne { template, args }.
attach(name, template, callable): void	Ajoute un filtre elm.<name> — utilisé en interne par #[Hook].
get(name): array|null	Récupère l'état d'un hook après résolution.
exist(name): bool	Vérifie si un hook a été enregistré.
formatName(string): string	Convertit / en . dans le nom du hook.

Le filtre WordPress elm.*

Chaque hook Twig génère un filtre WordPress nommé elm.<hookName>. Ce filtre reçoit et retourne un tableau { "template": string, "args": array }.

Vous pouvez l'utiliser directement avec add_filter() si nécessaire :

add_filter('elm.front-page.services', function (array $hook): array {
    return [
        'template' => get_stylesheet_directory() . '/views/services.html.twig',
        'args'     => array_merge($hook['args'], ['extra' => 'valeur']),
    ];
});

Préférez #[Hook]

L'utilisation de add_filter() directement est possible mais déconseillée. Préférez l'attribut #[Hook] pour une meilleure lisibilité et une intégration dans l'architecture Elementum.

Relation avec component()

La fonction component() intègre automatiquement le pipeline twig.hook. Chaque composant génère un hook interne nommé d'après son chemin (ex: front-page.about). Cela signifie que #[Hook] peut aussi surcharger un composant, sans utiliser hook() explicitement dans le template.

Bonnes pratiques

• Nommez les hooks de façon cohérente : utilisez le format section.element (ex: front-page.hero, header.nav).
• Utilisez before. et after. comme convention pour les points d'extension autour des composants.
• Ne transmettez que les variables nécessaires dans args pour garder le contexte Twig propre.
• Documentez vos hooks dans votre thème pour que les développeurs de thèmes enfants sachent quels points sont disponibles.