Comment migrer un plugin sur mesure vers Sylius 2 ?
Un plugin développé pour votre boutique se migre vers Sylius 2 en deux temps : d'abord le nettoyer sur Sylius 1.14 en supprimant ses dépréciations, ensuite réécrire ses points de contact avec Sylius, c'est-à-dire ses gabarits, ses écrans d'administration, ses transitions de commande, ses e-mails et ses ressources d'API. La logique métier, les entités et la plupart des services se conservent. On ne réécrit pas le plugin, on rebranche ce qu'il touche.
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, plugins maison compris. Cet article donne la méthode que j'applique. Si vous hésitez encore à faire ce travail en interne, lisez d'abord les conditions pour adapter soi-même un plugin. Pour les plugins tiers, la démarche est différente et décrite dans le guide de vérification des plugins.
Par où commencer pour adapter un plugin personnalisé à Sylius 2 ?
Par l'inventaire. Un plugin sur mesure vit parfois dans un dépôt privé installé par Composer, parfois directement dans le dossier src du projet sous forme de bundle. Dans les deux cas, listez ce qu'il touche : gabarits surchargés ou ajoutés, écrans d'administration, grilles, formulaires étendus, écouteurs sur les états de commande, e-mails, ressources d'API, commandes Messenger.
Cette liste se fait mieux avec un outil qu'à la main. Sylius Upgrade Analyzer, l'outil open source que j'ai créé et publié sur le Sylius Store, analyse le projet et signale chaque point incompatible avec Sylius 2 : template events, classes Semantic UI, configuration winzou, SwiftMailer, classes et routes supprimées, services renommés, appels directs au conteneur. Chaque problème porte une estimation, et plus de 40 corrections automatiques traitent les cas mécaniques, que je relis toujours avant de les garder.
Que préparer sur Sylius 1.14 avant le passage en 2.0 ?
Le chemin officiel passe par la 1.14, et c'est là qu'une bonne partie du travail se fait sans risque pour la production. Quatre chantiers sont possibles avant même de toucher à Sylius 2.
Premier chantier, les identifiants de services. Le guide officiel UPGRADE-2.0 précise que les alias introduits en 1.14 deviennent les identifiants principaux en 2.0, et que les anciens identifiants sont supprimés. Si votre plugin décore ou injecte un service Sylius par son ancien nom, passez dès maintenant au nouveau.
Deuxième chantier, la machine à états. Depuis la 1.13, Sylius fournit une abstraction, l'interface StateMachineInterface de l'espace de noms Sylius\Abstraction\StateMachine, qui fonctionne avec winzou comme avec Symfony Workflow. Un plugin qui appelle cette abstraction plutôt que winzou directement traversera la migration bien plus facilement.
Troisième chantier, les e-mails. SwiftMailer est retiré de Sylius 2 au profit de symfony/mailer. Un plugin qui construit ses propres messages peut basculer avant la migration.
Quatrième chantier, les dépréciations de façon générale. Faites tourner la boutique avec le journal des dépréciations actif et corrigez tout ce qui vient du plugin. C'est le travail le moins spectaculaire et le plus rentable.
Quels changements de Sylius 2 touchent un plugin maison ?
Les services et le conteneur
En Sylius 2.0, les services sont privés par défaut. Un plugin qui récupère un service Sylius avec un appel direct au conteneur casse au premier appel. Il faut injecter ce service par le constructeur. Profitez-en pour vérifier les signatures : le guide liste les constructeurs de classes Sylius qui ont changé, et toute classe de votre plugin qui en hérite doit suivre. L'autoconfiguration par interfaces de certains services, comme les processeurs de commande et les contextes de panier, se fait désormais par attributs, AsOrderProcessor et AsCartContext.
Les gabarits et l'administration
Les template events et Sonata Blocks disparaissent au profit des Twig Hooks. Chaque bloc que votre plugin injectait dans une page doit être déclaré comme hookable sur le bon point d'accroche. Les écrans en Semantic UI sont à réécrire en Bootstrap 5, et le JavaScript jQuery à remplacer, en général par des contrôleurs Stimulus. C'est souvent le poste le plus long, et je le détaille dans le guide pratique des Twig Hooks.
Les transitions de commande, de paiement et d'expédition
L'adaptateur par défaut de la machine à états passe de winzou à Symfony Workflow. Les callbacks winzou de votre plugin deviennent des écouteurs d'événements Workflow. Winzou reste installable en option, mais ce n'est qu'un sursis. La méthode complète est dans l'article sur le passage de winzou à Symfony Workflow.
Messenger, API et paiement
Les bus sylius_default.bus et sylius_event.bus sont remplacés par sylius.command_bus et sylius.event_bus. Si le plugin expose des ressources d'API, elles suivent le passage à une version majeure supérieure d'API Platform. S'il ajoute une passerelle de paiement, regardez le nouveau mécanisme des Payment Requests.
| Ce que fait le plugin | En Sylius 1.x | En Sylius 2 |
|---|---|---|
| Ajoute un bloc dans une page | Template event ou Sonata Block | Hookable déclaré dans un Twig Hook |
| Réagit à une commande payée | Callback winzou | Écouteur Symfony Workflow |
| Envoie un e-mail | SwiftMailer | symfony/mailer |
| Utilise un service Sylius | Appel direct au conteneur possible | Injection obligatoire, services privés |
| Lit la date courante | DateTimeProviderInterface de sylius/calendar | ClockInterface de symfony/clock |
Comment tester le plugin migré ?
Le squelette officiel Sylius PluginSkeleton dispose de branches pour chaque version 2.x et fournit une application de test dans tests/TestApplication. Faire tourner le plugin dans cette application vierge, avec PHPUnit et Behat, sépare les problèmes du plugin de ceux de la boutique. Si votre plugin maison n'a jamais eu de tests, écrivez au moins un scénario par parcours qu'il modifie : ajout au panier, paiement, changement d'état de commande, écran d'administration.
Ensuite seulement, installez le plugin sur la branche Sylius 2 de la boutique et rejouez les parcours de commande complets sur une copie des données réelles. Un plugin peut passer tous ses tests isolés et casser en contexte, par exemple parce qu'un autre plugin occupe le même point d'accroche.
Si vous voulez savoir précisément ce que votre plugin maison demande avant de lancer le chantier, je peux faire cette lecture pour vous dans le cadre du diagnostic de migration Sylius 2.
Ce que je vous propose
Un plugin sur mesure est presque toujours la partie la plus précieuse d'une boutique Sylius : c'est votre métier mis en code. Il mérite une migration méthodique, préparée sur la 1.14, plutôt qu'une réécriture précipitée. Le support de sécurité de la 1.14 s'arrête le 31 décembre 2026, ce qui laisse encore le temps de faire les choses dans l'ordre si le chantier démarre maintenant.
Je lance Sylius Upgrade Analyzer sur votre projet, je lis le code de vos plugins maison et je vous remets un diagnostic offert avec une estimation en jours, poste par poste.