Migrer Sylius 1.x vers 2.0 : Le Guide Complet

Sylius 2.0 represente la mise a jour la plus significative depuis la création du framework. Le passage de la version 1.x a la 2.0 implique des changements profonds sur le frontend, les machines a etats, le mailer, les paiements et l'API. Voici un guide structure pour aborder cette migration sereinement.

Les changements majeurs de Sylius 2.0

Frontend : adieu Semantic UI, bonjour Bootstrap 5

Le stack frontend est entierement remplace :

Semantic UI + jQuery cede la place a Bootstrap 5 + Symfony UX (Turbo, Stimulus)
Les templates utilisent desormais les Twig Hooks au lieu des overrides classiques
Toutes les interactions JavaScript doivent être reecrites en controllers Stimulus

State Machine : de winzou a Symfony Workflow

Le composant winzou/state-machine-bundle est remplace par Symfony Workflow. Les callbacks personnalises, les guards et les transitions doivent être reecrits sous forme d'event subscribers.

Mailer : SwiftMailer abandonne

SwiftMailer (abandonne en 2021) est remplace par symfony/mailer. Toutes les références a \Swift_Message et \Swift_Mailer doivent être mises a jour.

Paiements : Payment Requests (experimental)

Payum reste disponible, mais un nouveau système event-driven base sur Symfony Messenger (Payment Requests) est introduit. Les passerelles Stripe et PayPal Express Checkout de base ont ete retirees.

API Platform 2.7 vers 4

Les groupes de serialisation sont prefixes par sylius:
DataProviders deviennent StateProviders
DataPersisters deviennent StateProcessors
Nouveau schema XML metadata/resources-3.0

Etape 0 : Prerequis — Passer a Sylius 1.14 LTS

Avant de viser la 2.0, montez d'abord sur Sylius 1.14 avec Symfony 6.4 LTS. Corrigez toutes les deprecations a ce stade. Cela simplifie énormément le saut vers 2.0.

SYMFONY_DEPRECATIONS_HELPER=strict php bin/phpunit

Etape 1 : Audit des template overrides

C'est la plus grosse source de travail. Chaque fichier dans templates/bundles/SyliusShopBundle/ represente un override a analyser :

Quels changements ont ete apportes par rapport au template original ?
Peut-on convertir en Twig Hook ?
Certains overrides sont-ils devenus inutiles ?

Etape 2 : Traiter les composants deprecies

Migration State Machine

# Avant (winzou)
winzou_state_machine:
    sylius_order_checkout:
        callbacks:
            after:
                custom_callback:
                    on: ["complete"]
                    do: ["@app.callback", "onComplete"]

# Apres (Symfony Workflow)
framework:
    workflows:
        sylius_order_checkout:
            # ...

# Event Subscriber
class OrderCompleteSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            'workflow.sylius_order_checkout.completed.complete' => 'onComplete',
        ];
    }
}

Migration Mailer

// Avant
$message = (new \Swift_Message('Subject'))
    ->setFrom('noreply@shop.com')
    ->setTo($customer->getEmail());
$this->mailer->send($message);

// Apres
$email = (new Email())
    ->from('noreply@shop.com')
    ->to($customer->getEmail())
    ->subject('Subject');
$this->mailer->send($email);

Etape 3 : Vérifier la compatibilité des plugins

Pour chaque plugin tiers :

Vérifier si une version compatible 2.x existe sur le Sylius Addons Marketplace
Consulter les issues GitHub pour les plans de migration
Prevoir des alternatives ou des forks si nécessaire

Etape 4 : Migration Frontend

Si votre projet a un frontend personnalise (pas headless) :

Remplacer les classes Semantic UI par les équivalents Bootstrap
Reecrire le code jQuery en controllers Stimulus
Mettre a jour la configuration Webpack Encore

Etape 5 : Migration API Platform

// Avant : groupe de serialisation
#[Groups(['admin:product:index'])]

// Apres : prefixe sylius:
#[Groups(['sylius:admin:product:index'])]

Estimation de l'effort

Type de projet	Personnalisation	Duree estimée
Leger	<10 overrides, pas de plugins custom	2-5 jours
Moyen	10-30 overrides, 2-5 plugins	2-4 semaines
Lourd	30+ overrides, passerelles custom	1-3 mois

Automatiser l'audit avec Sylius Upgrade Analyzer

J'ai developpe un outil open-source (Sylius Upgrade Analyzer) qui scanne automatiquement votre projet et genere un rapport detaille :

composer require --dev pierre-arthur/sylius-upgrade-analyzer
vendor/bin/sylius-upgrade-analyzer sylius-upgrade:analyze

49 analyseurs couvrent templates, deprecations, plugins, grids et API Platform. Chaque problème est classé (BREAKING/WARNING/SUGGESTION) avec une estimation en heures.

Conclusion

La migration Sylius 2.0 est un vrai projet a part entiere. Ne la traitez pas comme un simple composer update. Planifiez, auditez, executez par phases, et communiquez avec vos parties prenantes. Les outils d'automatisation comme Sylius Upgrade Analyzer reduisent considerablement les risques d'oubli et accelerent la phase d'estimation.