Aller au contenu principal
Version: Next

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ètreTypeDéfautDescription
hookNamestring—Requis. Nom du hook. Les / sont convertis en . (front-page/services → front-page.services).
templatestring""Optionnel. Template Twig par défaut si aucun contrôleur n'est attaché.
argsarray[]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éthodeDescription
register(name, template, args): arrayEnregistre un hook et applique les filtres WordPress. Retourne { template, args }.
attach(name, template, callable): voidAjoute un filtre elm.<name> — utilisé en interne par #[Hook].
get(name): array|nullRécupère l'état d'un hook après résolution.
exist(name): boolVérifie si un hook a été enregistré.
formatName(string): stringConvertit / 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.