Sylius 2 : que deviennent nos migrations Doctrine ?

Avec Sylius 2, les anciennes migrations Doctrine de Sylius disparaissent : elles ont été regroupées dans une migration unique, qui ne fait rien sur une base 1.x existante et nettoie les anciennes entrées de la table de suivi. Vos propres migrations, celles de votre projet, ne bougent pas : elles restent dans votre code et dans la table, déjà marquées comme exécutées. Le travail consiste donc surtout à vérifier, sur une copie de la production, que l'historique est cohérent et que les nouvelles migrations de Sylius 2 passent sur vos données.

Je suis développeur Sylius indépendant et j'ai mené des montées de version 1.x vers 2.x en production. La question des migrations inquiète souvent les responsables techniques, parce que la phrase du guide officiel est courte et que le dossier des migrations de Sylius a fondu. Voici ce qui se passe réellement, vérifié dans le code de Sylius.

Que dit la documentation officielle sur les migrations Doctrine ?

Le guide UPGRADE-2.0 de Sylius consacre un court paragraphe au sujet : les migrations Doctrine ont été régénérées, tous les anciens fichiers ont été supprimés et leur contenu se trouve désormais dans une seule migration. Pour l'appliquer et se débarrasser des anciennes entrées, il suffit de lancer les migrations comme d'habitude, avec bin/console doctrine:migrations:migrate --no-interaction.

Concrètement, le dossier des migrations du cœur de Sylius 2 contient deux migrations régénérées, l'une pour MySQL et l'autre pour PostgreSQL, datées du 1er janvier 2016 pour passer avant toutes les autres. Chacune est ignorée sur la plateforme qui ne la concerne pas. Elles sont suivies des migrations propres à la version 2.

Que se passe-t-il sur une base Sylius 1.14 existante ?

C'est le point qui rassure. La migration régénérée commence par vérifier si une table du schéma 1.x est déjà présente. Si c'est le cas, elle ne crée rien : votre base n'est pas reconstruite. Après son passage, elle supprime de la table de suivi des migrations (nommée sylius_migrations dans la configuration standard) les anciennes entrées du cœur de Sylius qui n'ont plus de fichier correspondant.

Viennent ensuite les migrations qui modifient vraiment votre schéma. Sur la branche 2.0, elles créent la table des demandes de paiement, retirent les colonnes salt et encoder_name des tables d'utilisateurs, suppriment les colonnes locked, expires_at et credentials_expire_at, ajoutent une position aux images produit, modifient une contrainte de clé étrangère sur les valeurs d'options des variantes et ajoutent un indicateur à la configuration des passerelles de paiement. Les versions correctives suivantes en ajoutent quelques-unes.

Pour le dirigeant, la conséquence est claire : vos produits, vos clients et vos commandes restent dans la même base, sans réimport. Je détaille ce point côté métier dans l'article sur la conservation de la base de données.

Et nos propres migrations, celles du projet ?

Sylius n'a régénéré que les siennes. Les migrations écrites par votre équipe ou votre agence, souvent rangées dans src/Migrations sous l'espace de noms App\Migrations dans les projets 1.x, restent à leur place. Elles sont déjà enregistrées comme exécutées et ne seront pas rejouées. Inutile de les déplacer vers le dossier migrations/ du squelette Sylius 2 : votre configuration Doctrine continue de pointer vers l'emplacement actuel.

Il reste trois situations à surveiller.

Les migrations des plugins

Un plugin livre souvent ses propres migrations. Si sa version compatible Sylius 2 les a elle aussi regroupées ou renommées, la table de suivi garde des entrées sans fichier. La commande doctrine:migrations:status les signale. Une fois vérifié que leur contenu est bien présent en base, l'entrée se retire avec doctrine:migrations:version et l'option --delete, qui, comme le précise la documentation de Doctrine Migrations, ne fait qu'ajouter ou retirer la version de la table, sans rien exécuter.

Les anciennes migrations qui touchent des colonnes supprimées

Sur une base de production, vos anciennes migrations ne repassent pas. Mais sur une base neuve, celle d'un nouvel environnement de test ou d'un poste de développeur, toute la chaîne est rejouée : migrations de Sylius 2 d'abord, puis les vôtres. Une migration écrite il y a des années qui modifie une colonne retirée par Sylius 2 peut alors échouer. Je rejoue toujours l'ensemble sur une base vide pour le vérifier.

Le mapping Doctrine de vos entités

Si vos entités surchargées déclarent encore des champs supprimés par Sylius 2, comme locked sur un utilisateur, le schéma et le code divergent. La commande doctrine:schema:validate compare les deux. Une génération de migration avec doctrine:migrations:diff sur une copie de la base montre aussi ce que Doctrine voudrait encore changer : si elle propose quelque chose d'inattendu, il faut comprendre pourquoi avant d'aller plus loin.

Ces vérifications font partie de ce que je regarde lors du diagnostic de migration Sylius 2 : état de la table de suivi, migrations des plugins, entités surchargées et colonnes concernées.

Comment je teste les migrations avant la bascule

Je ne lance jamais les migrations de Sylius 2 pour la première fois sur la production. La méthode est toujours la même : une copie récente de la base de production, anonymisée si besoin, sur laquelle je joue la mise à jour complète, puis je contrôle l'état des migrations, la validation du schéma et quelques parcours réels (connexion d'un client ancien, commande, remboursement dans l'administration). Je chronomètre aussi l'opération : sur une grosse base, une migration qui modifie une table volumineuse peut prendre du temps, et cette durée sert à dimensionner la fenêtre de mise en production.

Point important : certaines de ces migrations suppriment des colonnes. Leur méthode de retour arrière recrée la colonne, pas les données qu'elle contenait. Le vrai filet de sécurité, c'est la sauvegarde complète prise juste avant la bascule, et dont la restauration a été testée. J'en parle en détail dans l'article sur la bascule sans coupure.

Sylius Upgrade Analyzer, l'outil que j'ai créé et publié sur le Sylius Store, repère dans le code les champs d'utilisateur supprimés et le mapping XML à convertir. La table de suivi et les données, elles, se vérifient sur la base elle-même.

Ce que je vous propose

Les migrations Doctrine sont rarement le poste le plus lourd d'une migration Sylius 2, mais c'est un poste où une erreur se paie le jour de la bascule. Avant le 31 décembre 2026, fin du support de sécurité de Sylius 1.14, je vous propose de lancer l'analyse sur votre projet, de vérifier l'état de vos migrations et de vos plugins, et de vous remettre un diagnostic offert avec une estimation en jours.