Sylius 2 : comment migrer nos templates Twig personnalisés ?
On migre des templates Twig personnalisés vers Sylius 2 en quatre temps : inventorier chaque surcharge, identifier ce qu'elle modifiait réellement dans la page, refaire cette modification avec le mécanisme Sylius 2 le plus léger (le plus souvent un Twig Hook), puis comparer les pages avant et après. On ne recopie pas les anciens fichiers en espérant qu'ils marchent : Sylius 2 a renommé et réorganisé ses gabarits, et une surcharge dont le chemin n'existe plus est ignorée sans erreur.
Je suis développeur Sylius indépendant et j'ai mené des montées de version 1.x vers 2.x de boutiques en production. Sur ces chantiers, les gabarits surchargés sont le poste que les équipes sous-estiment le plus, parce qu'ils se sont accumulés par petites touches pendant des années. Le fonctionnement des hooks eux-mêmes est expliqué dans mon guide pratique des Twig Hooks ; ici, je traite la méthode globale pour faire passer tout un parc de surcharges.
Pourquoi les anciens templates ne passent-ils pas tels quels ?
Parce que trois fondations ont changé en même temps. Le guide officiel UPGRADE-2.0 annonce la suppression des Sonata Blocks et du système de template events, remplacés par les Twig Hooks. Il décrit aussi une nouvelle arborescence : les gabarits sont désormais regroupés par ressource et alignés sur les noms de hooks, là où Sylius 1.x mélangeait des dossiers comme Product/Form ou Crud. Enfin, le balisage est passé de Semantic UI à Bootstrap 5.
La conséquence la plus traîtresse vient de la règle de surcharge de Symfony. Selon la documentation Symfony sur la surcharge des bundles, un fichier placé dans templates/bundles/<NomDuBundle>/ ne remplace l'original que s'il porte le même nom et le même chemin. Si Sylius a déplacé ce gabarit, votre fichier reste sur le disque, ne provoque aucune erreur, et n'est plus jamais affiché. La page montre alors le rendu par défaut de Sylius 2, et votre personnalisation disparaît en silence.
Comment inventorier les templates surchargés ?
Je commence par la liste exhaustive, avant de toucher à quoi que ce soit. Elle se trouve à trois endroits : le dossier templates/bundles/ pour les surcharges des bundles Sylius, les dossiers de thèmes si la boutique utilise SyliusThemeBundle, et la configuration des template events (la clé sylius_ui, souvent dans un fichier events.yaml) pour les blocs injectés sans surcharge. Il faut y ajouter les gabarits qui appellent des routes partielles avec render(url(...)) ou render(controller(...)), car le guide de mise à niveau indique que toutes les routes partielles ont été supprimées et remplacées par des composants Twig.
C'est le travail que fait Sylius Upgrade Analyzer, l'outil open source que j'ai créé et publié sur le Sylius Store : il compte les gabarits surchargés, repère les dépendances supprimées et associe une estimation en heures à chaque problème. Je relis ensuite chaque fichier à la main pour noter ce qu'il change réellement : souvent trois lignes dans un fichier de deux cents.
Quel mécanisme Sylius 2 pour chaque type de surcharge ?
Une fois la liste établie, chaque surcharge se range dans une catégorie, et chaque catégorie a son équivalent. Le système de hooks est documenté dans la documentation de Sylius Stack : on déclare des hookables sous la clé sylius_twig_hooks, chacun rendant un gabarit ou un composant Twig, avec une priorité, une option enabled et une condition éventuelle.
| Ce que faisait la surcharge 1.x | Équivalent en Sylius 2 |
|---|---|
| Ajouter un bloc (bandeau, mention, champ) via un template event | Un nouveau hookable sur le hook concerné |
| Modifier un morceau d'un gabarit recopié en entier | Remplacer le seul hookable qui rend ce morceau |
| Masquer un élément d'origine | Le hookable correspondant avec enabled: false |
| Changer l'ordre des blocs | La priority des hookables, la plus haute s'affichant en premier |
| Afficher un bloc seulement pour certains visiteurs | L'option condition, évaluée à chaque rendu |
| Charger un fragment par une route partielle | Un composant Twig, ou un Live Component s'il doit se mettre à jour |
| Changer toute la structure d'une page | Surcharge complète du gabarit, en dernier recours |
L'intérêt pour vous est durable. Une surcharge complète fige une copie du gabarit de Sylius à une date donnée : à chaque mise à jour, il faut la comparer à l'original. Un hookable ne touche que votre morceau, et les montées de version 2.x suivantes deviennent beaucoup moins coûteuses. Pour les cas où la surcharge complète reste justifiée, je renvoie à ma méthode de surcharge des templates.
Quels pièges surveiller dans le code Twig lui-même ?
Au-delà de la structure, le contenu des gabarits doit être relu. Le guide de mise à niveau liste plusieurs extensions Twig retirées de SyliusUiBundle, comme celle du filtre sort_by, des helpers de templating supprimés comme PriceHelper, et la variable globale use_webpack, devenue inutile puisque Webpack est désormais le seul outil de build. Les classes Semantic UI sont à traduire en Bootstrap 5, et tout script jQuery glissé dans un gabarit cesse de fonctionner, puisque Sylius ne charge plus jQuery.
Quand une route partielle devient un composant, les données ne sont pas forcément exposées au gabarit sous le même nom qu'avant. Je ne me fie donc jamais à un gabarit qui « s'affiche » : je vérifie qu'il affiche les bonnes données, sur des cas réels comme un produit à déclinaisons, un panier avec promotion ou un client sans adresse.
Si votre boutique accumule des dizaines de surcharges et que vous ne savez pas lesquelles comptent vraiment, c'est exactement ce que démêle le diagnostic de migration Sylius 2 : la liste, le mécanisme cible pour chacune et le temps nécessaire.
Dans quel ordre migrer les templates ?
Je procède par valeur commerciale, pas par ordre alphabétique. D'abord le tunnel qui encaisse : panier, adresse, livraison, paiement, confirmation. Ensuite les pages qui attirent : fiche produit, listes de catégories, recherche. Puis le compte client et les e-mails, et enfin les pages secondaires. L'administration se traite à part, sur sa propre liste.
Chaque lot se termine par une comparaison visuelle et fonctionnelle entre la boutique 1.14 et la branche Sylius 2, sur les mêmes données. C'est la seule façon de repérer les surcharges ignorées en silence décrites plus haut. Pour un design très travaillé, la stratégie d'ensemble est détaillée dans l'article sur le storefront fortement personnalisé.
Ce que je vous propose
Les correctifs de sécurité de Sylius 1.14 s'arrêtent le 31 décembre 2026, et les gabarits sont souvent le chemin critique du chantier. Je lance Sylius Upgrade Analyzer sur votre projet, je classe chaque surcharge selon le mécanisme Sylius 2 qui la remplace, et je vous remets un diagnostic offert avec une estimation en jours. Je vous rappelle sous 24 heures ouvrées pour le commenter.