Comment remplacer SwiftMailer dans Sylius 2 ?
Pour remplacer SwiftMailer dans Sylius 2, on passe à Symfony Mailer, la seule bibliothèque d'envoi que Sylius 2 accepte. La bonne méthode consiste à le faire avant la migration, sur Sylius 1.14, qui contient déjà Symfony Mailer : on change l'adaptateur d'envoi, on réécrit la configuration de connexion et le code qui manipule directement des objets SwiftMailer, puis on teste chaque e-mail qui part de la boutique. Sur une boutique qui n'envoie que les e-mails standards de Sylius, c'est un chantier court.
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. Les e-mails sont un sujet que les dirigeants sous-estiment : une confirmation de commande qui ne part plus, ce sont des appels au service client et des clients qui doutent d'avoir payé.
Que dit la documentation officielle sur SwiftMailer ?
Le guide UPGRADE-2.0 de Sylius est direct : la dépendance swiftmailer/swiftmailer a été retirée, il faut utiliser symfony/mailer à la place. Derrière cette ligne, il y a le bundle d'e-mails de Sylius, SyliusMailerBundle, par lequel passent tous les envois de la boutique. Sa version 1.x proposait deux adaptateurs, l'un pour SwiftMailer et l'autre pour Symfony Mailer. Sa version 2, exigée par Sylius 2, a retiré le support de SwiftMailer.
La raison de fond est simple. Le dépôt officiel de SwiftMailer annonce que la bibliothèque n'est plus maintenue depuis fin novembre 2021 et renvoie vers Symfony Mailer, présenté comme son successeur. Une boutique qui envoie encore ses e-mails avec SwiftMailer utilise donc un composant sans correctif depuis plusieurs années.
Comment passer de SwiftMailer à Symfony Mailer, étape par étape ?
Changer l'adaptateur d'envoi sur la 1.14
Sylius 1.14 dépend déjà de symfony/mailer. Le piège est ailleurs : quand SwiftMailer et Symfony Mailer sont installés tous les deux et qu'aucun adaptateur n'est configuré, le bundle d'e-mails de Sylius 1.x choisit SwiftMailer en premier. Installer Symfony Mailer ne suffit donc pas. Il faut le désigner explicitement avec l'option sender_adapter de la configuration sylius_mailer, en lui donnant le service sylius.email_sender.adapter.symfony_mailer, ou retirer SwiftMailer du projet.
Réécrire la configuration de connexion
SwiftMailer et Symfony Mailer n'utilisent pas la même configuration. Symfony Mailer lit sa connexion dans la variable d'environnement MAILER_DSN, qui décrit le transport : un serveur SMTP ou un prestataire d'envoi. Les anciens réglages de SwiftMailer, souvent dans config/packages/swiftmailer.yaml et une variable d'environnement dédiée, deviennent inutiles. Il faut reporter les bons identifiants dans chaque environnement, sans oublier les serveurs de tâches planifiées s'ils envoient des e-mails.
Remplacer le code qui manipule SwiftMailer directement
C'est la partie qui varie d'un projet à l'autre. Les e-mails standards de Sylius passent par son interface d'envoi et ne demandent rien de plus. Mais un développement sur mesure qui construit lui-même un Swift_Message, joint une facture avec Swift_Attachment ou injecte le service Swift_Mailer doit être réécrit avec les classes de Symfony Mailer et du composant Mime, comme Email et MailerInterface. Sylius Upgrade Analyzer, l'outil open source que j'ai créé et publié sur le Sylius Store, repère ces usages dans le code et sait convertir automatiquement les cas simples. Je relis toujours le résultat.
Retirer SwiftMailer
Une fois la boutique 1.14 en production avec Symfony Mailer et les envois vérifiés, on retire swiftmailer/swiftmailer et symfony/swiftmailer-bundle du projet, ainsi que leur configuration. Le jour de la migration vers Sylius 2, le sujet est clos.
Si vous voulez savoir combien d'endroits de votre code dépendent encore de SwiftMailer, c'est l'une des lignes du diagnostic de migration Sylius 2 offert.
Qu'est-ce qui change d'autre pour les e-mails dans Sylius 2 ?
Le changement de bibliothèque n'est pas le seul. Le guide UPGRADE-2.0 déplace les gestionnaires d'e-mails de commande, d'expédition et de contact vers l'espace de noms Sylius\Bundle\CoreBundle\Mailer, retire les anciennes classes des bundles Shop et Admin, et supprime le paramètre sylius.mailer.templates. Il supprime aussi la réinitialisation de mot de passe par code PIN, avec l'e-mail qui allait avec. Un projet qui a surchargé ou décoré ces services doit les adapter. Si votre boutique utilise une classe retirée, la méthode générale est décrite dans l'article sur les classes supprimées dans Sylius 2.
Comment tester les e-mails avant la mise en production ?
Je dresse d'abord la liste de tous les e-mails qui partent de la boutique : confirmation de commande, confirmation d'expédition, création de compte, vérification d'adresse, mot de passe oublié, formulaire de contact, et tous ceux ajoutés par des plugins ou du code sur mesure, comme l'envoi de facture ou les relances. Pour chacun, je déclenche le parcours réel en recette, avec un transport qui capture les messages au lieu de les envoyer, et je vérifie le destinataire, l'expéditeur, le contenu, la langue et les pièces jointes.
Deux contrôles évitent les mauvaises surprises après la bascule. Le premier : vérifier que l'adresse d'expédition et le domaine restent autorisés par votre prestataire d'envoi, sinon les messages finissent en indésirables. Le second : surveiller les journaux d'erreurs les premiers jours, car un e-mail qui échoue ne bloque pas toujours la commande, et personne ne le remarque.
Ce que je vous propose
Remplacer SwiftMailer est un des rares chantiers de la migration que l'on peut livrer dès aujourd'hui, sur la 1.14, sans attendre le reste. C'est aussi un bon moyen d'avancer avant le 31 décembre 2026, fin du support de sécurité de Sylius 1.14. Je lance Sylius Upgrade Analyzer sur votre projet, je liste les e-mails et le code concernés, et je vous remets un diagnostic offert avec une estimation en jours.