Twig Hooks dans Sylius 2.0 : Guide Pratique de Migration

Les Twig Hooks sont le mecanisme de personnalisation recommandé dans Sylius 2.0, remplacant les template overrides classiques. Ce guide pratique montre comment migrer vos overrides existants.

Pourquoi les Twig Hooks ?

Les template overrides posent un problème fondamental : quand Sylius met a jour un template, votre override ne bénéficie pas des corrections. Vous devez manuellement reporter chaque changement.

Les Twig Hooks resolvent cela en permettant d'injecter du contenu a des points precis sans copier le template entier :

• Maintenabilite : vos customisations sont isolees
• Upgradabilite : les mises a jour Sylius s'appliquent sans conflit
• Composabilite : plusieurs modules peuvent se brancher sur le même hook

Anatomie d'un Twig Hook

Un hook est declare dans le template Sylius avec :

{# Dans le template Sylius #}
{{ sylius_hook('sylius.shop.product.show.content') }}

Vous vous y branchez via la configuration :

# config/packages/sylius_twig_hooks.yaml
sylius_twig_hooks:
    hooks:
        'sylius.shop.product.show.content':
            custom_reviews:
                template: 'shop/product/custom_reviews.html.twig'
                priority: 10

Migration pas a pas

Etape 1 : Identifier ce que fait votre override

Comparez votre override avec le template original de Sylius. Dans la plupart des cas, vous avez :

• Ajoute un bloc de contenu (reviews, badges, CTA...)
• Modifie l'affichage d'un élément existant
• Supprime un élément

Etape 2 : Trouver le hook correspondant

Sylius 2.0 expose des hooks sur la majorite des templates. Consultez la documentation ou utilisez le profiler Symfony (onglet Twig Hooks) pour découvrir les hooks disponibles sur chaque page.

# Activer le debug des hooks
# config/packages/dev/sylius_twig_hooks.yaml
sylius_twig_hooks:
    enable_debug: true

Etape 3 : Créer votre template hook

{# templates/shop/product/custom_badge.html.twig #}
{% if product.isNew %}
    Nouveau
{% endif %}

Etape 4 : Enregistrer le hook

sylius_twig_hooks:
    hooks:
        'sylius.shop.product.show.header':
            new_badge:
                template: 'shop/product/custom_badge.html.twig'
                priority: 50

Patterns courants

Ajouter du contenu après un élément

# Priorite basse = affiche apres les hooks existants
sylius_twig_hooks:
    hooks:
        'sylius.shop.product.show.content':
            custom_section:
                template: 'shop/product/section.html.twig'
                priority: -10

Remplacer un élément existant

# Desactivez le hook par defaut, ajoutez le votre
sylius_twig_hooks:
    hooks:
        'sylius.shop.product.show.price':
            default:
                enabled: false
            custom_price:
                template: 'shop/product/custom_price.html.twig'
                priority: 0

Passer des donnees au hook

sylius_twig_hooks:
    hooks:
        'sylius.shop.layout.header':
            promo_banner:
                template: 'shop/promo_banner.html.twig'
                context:
                    message: "Livraison gratuite des 50EUR"
                    color: "warning"

Pieges a éviter

Ne pas migrer les overrides qui touchent la structure

Si votre override modifie profondement la structure HTML (grille, layout), un hook simple ne suffira pas. Dans ce cas, gardez l'override temporairement et planifiez une refonte avec Bootstrap 5.

Attention aux priorites

Les hooks s'executent par priorite decroissante. Si vous placez tout a la même priorite, l'ordre devient imprevisible.

Hooks et cache

Les Twig Hooks sont resolus a la compilation du template. Pas de surcharge de performance a runtime, mais pensez a vider le cache après toute modification de configuration.

Audit automatique avec Sylius Upgrade Analyzer

L'analyseur detecte automatiquement vos overrides et identifie les hooks disponibles pour chacun :

vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze --category=templates

Le rapport indique pour chaque override : le hook de destination, la complexité de migration, et le temps estimé.

Conclusion

Les Twig Hooks demandent un investissement initial mais simplifient drastiquement la maintenance long terme. Commencez par les overrides les plus simples (ajout de contenu) et progressez vers les cas complexes. L'outil d'audit identifie vos quick wins.