Migration vers Symfony 7 et Sylius 2.0 : checklist technique pour les devs PHP

Sylius 2.0 repose désormais sur Symfony 7. Pour les équipes qui maintiennent des projets Sylius 1.x sous Symfony 5 ou 6, cette migration représente une modernisation majeure de la stack. Voici une checklist concrète pour aborder cette transition sereinement, étape par étape.

Source originale : Symfony 7 and Sylius 2.0: What Changes for Developers par Pierre-Arthur Demengel.

1. Mettre à jour l'environnement runtime : PHP 8.3 obligatoire

Symfony 7 exige PHP 8.2 minimum, mais Sylius 2.0 pousse la contrainte à PHP 8.3. C'est le premier prérequis non négociable.

Si vos serveurs de production tournent encore en PHP 8.1, l'upgrade runtime est votre point de départ. Côté Docker, cela se traduit par une mise à jour de vos images de base :

# Avant
FROM php:8.1-fpm-alpine

# Après
FROM php:8.3-fpm-alpine

Pensez à aligner vos environnements de dev, CI et prod pour éviter les surprises. PHP 8.3 apporte des avantages concrets : classes readonly, constantes de classe typées, fonction json_validate(), et des gains de performance mesurables.

2. Corriger les suppressions de Symfony 7 : les breaking changes critiques

Symfony 7 est la version qui transforme toutes les deprecations du cycle 6.x en erreurs fatales. Voici les trois points d'attention prioritaires pour un projet Sylius.

Sécurité : security.encoders → security.password_hashers

L'ancienne configuration security.encoders est définitivement supprimée. Il faut migrer vers security.password_hashers dans config/packages/security.yaml :

# Avant (Symfony 5/6)
security:
    encoders:
        App\Entity\User:
            algorithm: bcrypt

# Après (Symfony 7)
security:
    password_hashers:
        App\Entity\User:
            algorithm: auto

Mailer : SwiftMailer est mort, vive symfony/mailer

L'intégration SwiftMailer est complètement supprimée. Si votre projet envoie encore des emails via SwiftMailer, la migration vers symfony/mailer est obligatoire :

composer remove symfony/swiftmailer-bundle
composer require symfony/mailer

Les Mailer et MailerInterface de Symfony remplacent Swift_Mailer. Vos services d'envoi d'email devront être réécrits pour utiliser Email et MailerInterface.

Routing : les annotations @Route → attributs PHP #[Route]

Le routing par annotations est supprimé au profit des attributs PHP natifs (disponibles depuis PHP 8.0) :

// Avant
/**
 * @Route("/product/{slug}", name="product_show")
 */
public function show(string $slug): Response { ... }

// Après
#[Route('/product/{slug}', name: 'product_show')]
public function show(string $slug): Response { ... }

Cette transformation peut être automatisée avec Rector (voir section suivante).

3. Automatiser la migration avec Rector et sécuriser avec PHPStan

Migrer manuellement des milliers de lignes de code n'est pas une option réaliste. Deux outils sont indispensables.

Rector : refactoring automatique

Rector applique des règles de transformation automatique du code. Pour une migration Symfony 7, on utilisera les sets dédiés :

composer require rector/rector --dev

// rector.php
use Rector\Config\RectorConfig;
use Rector\Symfony\Set\SymfonySetList;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/src'])
    ->withSets([
        SymfonySetList::SYMFONY_70,
        SymfonySetList::SYMFONY_CODE_QUALITY,
        SymfonySetList::ANNOTATIONS_TO_ATTRIBUTES,
    ]);

# Prévisualiser les changements
vendor/bin/rector process --dry-run

# Appliquer
vendor/bin/rector process

PHPStan : détecter les régressions de type

Après le passage de Rector, un audit statique avec PHPStan permet de détecter les incompatibilités résiduelles :

composer require phpstan/phpstan phpstan/extension-installer --dev
composer require phpstan/phpstan-symfony --dev

Visez au minimum le niveau 6, idéalement le niveau 8 pour un projet Sylius solide :

vendor/bin/phpstan analyse src --level=6

4. Intégrer la détection de régressions dans le pipeline CI/CD

Une migration réussie ne s'arrête pas à une exécution locale. Les régressions doivent être détectées automatiquement à chaque push.

Voici un exemple de job GitHub Actions pour un pipeline minimaliste :

name: CI

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP 8.3
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Install dependencies
        run: composer install --no-interaction

      - name: PHPStan
        run: vendor/bin/phpstan analyse src --level=6

      - name: Rector (dry-run)
        run: vendor/bin/rector process --dry-run

      - name: Tests
        run: php bin/phpunit

Ce pipeline garantit qu'aucune régression ne passe en revue de code sans être signalée.

Conclusion

La migration vers Symfony 7 et Sylius 2.0 est substantielle, mais parfaitement structurable si l'on suit un ordre logique :

1. ✅ Mettre à jour l'image Docker vers PHP 8.3
2. ✅ Corriger security.encoders → security.password_hashers
3. ✅ Migrer SwiftMailer vers symfony/mailer
4. ✅ Convertir les annotations @Route en attributs #[Route] via Rector
5. ✅ Auditer avec PHPStan niveau 6+
6. ✅ Automatiser la détection de régressions en CI

Chaque étape peut être traitée indépendamment, ce qui permet une migration progressive sans bloquer la livraison de features. L'investissement en outillage (Rector, PHPStan, CI) paie bien au-delà de cette migration.