Comment migrer API Platform 2.7 vers 4 avec Sylius 2 ?

Avec Sylius 2, on ne migre pas API Platform à part : on passe directement d'API Platform 2.7, utilisé par Sylius 1.14, à API Platform 4, exigé dès Sylius 2.0. Il n'y a pas d'étape intermédiaire en version 3 à mettre en production. Le travail porte sur votre code d'API personnalisé (les DataProviders et DataPersisters deviennent des providers et des processors), sur les ressources et les groupes de sérialisation, et surtout sur les outils qui consomment votre API, car plusieurs routes et réponses de Sylius ont changé.

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. Le code détaillé de la conversion se trouve dans le guide technique migrer l'API Sylius d'API Platform 2.7 vers la version 4. Ici, je réponds à la question de méthode, en commençant par vérifier ce que chaque version de Sylius exige réellement.

Quelle version d'API Platform chaque version de Sylius exige-t-elle ?

J'ai relevé les contraintes dans le fichier composer.json de chaque branche de Sylius. Depuis la 2.0, Sylius ne dépend plus du paquet monolithique api-platform/core, mais des paquets séparés d'API Platform, comme api-platform/symfony et api-platform/doctrine-orm.

Conséquence pratique : votre version cible de Sylius fixe la version d'API Platform. Viser Sylius 2.3, la cible que je recommande en général, c'est viser au moins API Platform 4.3, avec la possibilité de la version 5. Le choix de cette version cible se fait donc en même temps que celui de Sylius.

Que dit la documentation officielle sur la migration de l'API ?

Sylius publie un guide dédié à l'API, UPGRADE-API-2.0. Il décrit les changements du côté de Sylius. Les DataProviders et DataPersisters de Sylius deviennent des classes rangées dans les espaces StateProvider et StateProcessor. Les DataTransformers disparaissent, certains étant remplacés par des constructeurs de contexte de sérialisation. Les groupes de sérialisation sans préfixe sont supprimés : un groupe comme admin:product:index devient sylius:admin:product:index. Plusieurs routes changent, par exemple les images produit, les coupons de promotion ou les provinces, qui passent sous leur ressource parente. Certaines ressources ne sont plus exposées, comme la configuration des passerelles de paiement ou les traductions, désormais intégrées à leur ressource principale.

Côté API Platform, le guide de mise à niveau de la version 2.7 pose les bases : les providers et processors remplacent les DataProviders et DataPersisters, la notion d'opérations « item » et « collection » disparaît au profit d'opérations par verbe HTTP, et l'attribut ApiResource change d'espace de noms. La version 2.7 contient déjà ce nouveau système et une commande api:upgrade-resource pour convertir les déclarations. En pratique, je ne bascule pas une boutique 1.14 entière sur ce nouveau système avant la migration, parce que l'API de Sylius 1.x elle-même repose sur les anciens DataProviders et DataPersisters.

Comment migrer l'API de votre boutique, étape par étape ?

Savoir qui consomme votre API

C'est la première question, et elle n'est pas technique. Une application mobile, un front headless, un ERP, un outil de gestion des stocks, un comparateur de prix : chacun appelle des routes précises. Je pars des journaux d'accès du serveur pour lister les routes réellement appelées, et je les compare aux changements listés par Sylius. Le résultat est une liste courte : les appels qui continueront de fonctionner, et ceux qui casseront.

Inventorier votre code d'API personnalisé

Ressources ajoutées, opérations sur mesure, extensions de requête, filtres, normaliseurs, groupes de sérialisation étendus : tout ce que votre équipe a ajouté à l'API doit passer aux interfaces d'API Platform 4. Sylius Upgrade Analyzer, l'outil open source que j'ai créé et publié sur le Sylius Store, contient des analyseurs dédiés à API Platform qui repèrent les anciennes annotations, les DataProviders, les DataPersisters et l'ancien espace de noms, et propose des corrections automatiques pour les remplacements de noms simples.

Écrire des tests de contrat avant de toucher au code

Pour chaque route utilisée par un consommateur, j'enregistre la requête et la réponse attendue sur la 1.14. Ces tests servent ensuite de référence sur la branche Sylius 2 : un champ disparu ou un format modifié se voit immédiatement, au lieu d'être découvert par l'application mobile en production.

Prévenir les consommateurs

Quand une route change, il faut adapter le client, pas seulement le serveur. Je prépare pour chaque intégration la liste des modifications à faire, et je cale leur mise en production avec la bascule. C'est souvent l'agence de l'application mobile ou l'éditeur de l'ERP qui fixe le calendrier réel.

Si votre boutique alimente des outils externes par l'API, ce travail d'inventaire fait partie du diagnostic de migration Sylius 2 offert. Les questions de synchronisation des stocks et des commandes sont traitées dans l'article sur les outils ERP, CRM et logistiques.

Que veut dire cette migration pour le dirigeant ?

Si votre boutique n'expose pas d'API à des outils tiers, le sujet est surtout technique et suit la migration de Sylius. Si elle alimente une application mobile ou un ERP, c'est l'un des postes à risque : une API cassée ne se voit pas sur le site, mais elle arrête des commandes ou des expéditions. Le coût dépend moins d'API Platform que du nombre de consommateurs et de développements sur mesure.

Ce que je vous propose

Avant le 31 décembre 2026, fin du support de sécurité de Sylius 1.14, mieux vaut savoir quelles intégrations dépendent de votre API et lesquelles devront évoluer. Je lance Sylius Upgrade Analyzer sur votre projet, je croise ses résultats avec les routes réellement appelées, et je vous remets un diagnostic offert avec la version cible, les intégrations concernées et une estimation en jours.