Sylius10 min

Sylius Template Override : la methode propre en 2026

Par Pierre-Arthur Demengel
SyliusTemplateTwigOverrideSymfony
Partager

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

SituationMethode 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 layoutOverride complet du layout
Changer completement le design d'une pageTheme complet
Correction urgente d'un bug dans un templateOverride 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.

Questions fréquentes

Partager
Spécialiste SyliusCréation Site Pro, reprise en 2023France, Belgique, LuxembourgDisponible immédiatement

Votre boutique vend plus que votre outil ne suit ?

Je vous rappelle sous 24 heures ouvrées et je vous dis ce que votre outil vous coûte.

Ou appelez directement :06 95 41 30 25