Sylius Template Override : la methode propre en 2026

Surcharger un template Sylius semble simple : copier le fichier, le modifier, c'est fait. Mais cette approche naive cree une dette technique qui explose lors des mises a jour. Voici la methode propre, adaptee a Sylius 2.x.

L'ancienne methode : vendor override

Avant Sylius 2.x, la methode standard pour modifier un template etait le vendor override Symfony :

# Copier le template original
cp vendor/sylius/sylius/src/Sylius/Bundle/ShopBundle/Resources/views/Product/show.html.twig \
   templates/bundles/SyliusShopBundle/Product/show.html.twig

# Modifier votre copie

Ca fonctionne, mais les problemes arrivent vite :

• Vous devez copier le template en entier, meme pour changer une ligne
• Les mises a jour Sylius ne se propagent pas dans vos overrides
• Apres 2-3 versions, vos templates divergent dangereusement du core
• Deux plugins ne peuvent pas modifier le meme template sans conflit

La methode moderne : Twig Hooks (Sylius 2.x)

Sylius 2.x introduit les Twig Hooks, un systeme d'injection de contenu a des points precis des templates. Le template parent reste intact, vous ajoutez ou remplacez des blocs specifiques.

Ajouter du contenu a un hook existant

# 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: 50

{# templates/shop/product/_custom_reviews.html.twig #}
<section class="mt-8 border-t pt-6">
  <h3 class="text-xl font-bold mb-4">Avis clients verifies</h3>
  {# Votre composant d'avis #}
</section>

Remplacer un hook existant

sylius_twig_hooks:
  hooks:
    'sylius_shop.product.show.images':
      # Desactiver le composant par defaut
      default:
        enabled: false
      # Le remplacer par le votre
      custom_gallery:
        template: 'shop/product/_custom_gallery.html.twig'
        priority: 100

Les hooks disponibles

Sylius 2.x expose des hooks dans tous les templates principaux. Pour les lister :

# En mode dev, activez le debug des hooks
# config/packages/dev/sylius_twig_hooks.yaml
sylius_twig_hooks:
  enable_autoprefixing: true

# Puis dans le profiler Symfony, onglet "Twig Hooks"
# Vous verrez tous les hooks disponibles et leur contenu

Quand utiliser quelle methode

Situation	Methode recommandee
Ajouter un element (bandeau, widget, section)	Twig Hook - ajout
Remplacer un composant specifique (galerie, prix)	Twig Hook - remplacement
Modifier la structure HTML globale du layout	Override complet du layout
Changer completement le design d'une page	Theme complet
Correction urgente d'un bug dans un template	Override temporaire + PR upstream

Migration depuis les template events

Si votre projet utilise encore les anciens sylius_template_event ou sonata_block_render_event de Sylius 1.x, voici comment migrer :

{# Avant (Sylius 1.x) #}
{{ sylius_template_event('sylius.shop.product.show.content', {'product': product}) }}

{# Apres (Sylius 2.x) #}
{% hook 'sylius_shop.product.show.content' with {'product': product} %}

Notre Sylius Upgrade Analyzer detecte automatiquement ces patterns et propose des auto-fixers pour la conversion.

Bonnes pratiques

• Privilegiez toujours les Twig Hooks aux overrides complets
• Nommez vos hooks clairement : monplugin_product_reviews plutot que custom_1
• Documentez vos overrides : notez pourquoi vous avez surcharge tel template
• Verifiez apres chaque mise a jour Sylius que vos overrides sont toujours necessaires
• Testez visuellement : un changement de template peut casser l'UI sans erreur PHP

Pour aller plus loin, consultez notre guide complet de creation de theme Sylius.