Twig Hooks dans Sylius 2.0 : Guide Pratique de Migration

Les Twig Hooks sont le mecanisme de personnalisation recommande 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 probleme fondamental : quand Sylius met à jour un template, votre override ne beneficie pas des corrections. Vous devez manuellement reporter chaque changement.

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

• Maintenabilite : vos customisations sont isolees
• Upgradabilite : les mises à jour Sylius s'appliquent sans conflit
• Composabilite : plusieurs modules peuvent se brancher sur le meme 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 à 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 element existant
• Supprime un element

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 decouvrir 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 : Creer 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 apres un element

# 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 element 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 à eviter

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 à la meme priorite, l'ordre devient imprevisible.

Hooks et cache

Les Twig Hooks sont resolus à la compilation du template. Pas de surcharge de performance à runtime, mais pensez à vider le cache apres 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 complexite de migration, et le temps estime.

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.