Migration Symfony 5 vers 6 : Guide complet (de 5.x à 6.4 LTS)

La version 6.4 de Symfony sortie en novembre 2023 ne se contente pas de succéder à la 5.4 ; elle marque la fin de l’héritage PHP 7. En basculant sur cette version, vous quittez un mode de compatibilité transitoire pour une architecture nativement conçue pour les standards actuels du langage.

Voici pourquoi cette migration est indispensable pour la santé de votre projet :

• Exploitation native de PHP 8.1+ : Contrairement à la 5.4 qui supportait encore PHP 7.2, Symfony 6.4 est entièrement typé et conçu pour PHP 8.1 minimum. Vous bénéficiez nativement des Enums, des Readonly properties et des Constructor Property Promotion au cœur même du framework.
• Performance accrue du Service Container : Le moteur de Symfony 6 a été optimisé pour réduire l’empreinte mémoire lors de la compilation du container. Le chargement des services est plus rapide, ce qui se traduit par un gain de temps de réponse sur chaque requête.
• Sécurité renforcée avec le nouveau composant Security : Symfony 6 abandonne définitivement l’ancien système de sécurité (les “Guard authenticators”) au profit d’un système d’authentification simplifié et plus robuste. C’est le moment idéal pour assainir vos configurations security.yaml.
• Dette technique et dépréciations : Rester en 5.4, c’est accumuler une dette liée aux couches de compatibilité. La version 6.4 nettoie des centaines de méthodes obsolètes, rendant votre base de code plus légère, plus lisible et plus facile à maintenir pour les nouveaux développeurs.
• Rampe de lancement pour Symfony 7 : Puisque la version 6.4 est le miroir fonctionnel de la version 7.0, réussir cette migration signifie que votre application est déjà virtuellement prête pour la prochaine génération du framework.

Sommaire de la migration

1. Étape 1 : Phase de nettoyage et d’audit
2. Étape 2 : Mise à jour de la version 5.4 (Dernière version mineure)
3. Étape 3 : Migration vers php 8.1+
4. Étape 4 : Traitement des dépréciations
5. Étape 5 : Bascule vers Symfony 6.4
6. Étape 6 : Phase de tests et validation

Étape 1 : Phase de nettoyage et d’audit

Avant de modifier la moindre ligne de configuration Symfony, il est crucial d’assainir votre projet. Migrer du code mort ou des dépendances obsolètes est une perte de temps et une source d’erreurs inutiles.

Suppression du code mort

Une migration est l’occasion parfaite pour faire l’inventaire de votre application et identifier le code mort. Vous pouvez utiliser des outils comme Rector (avec le jeu de règles DeadCode) ou PHPStan pour détecter les méthodes, propriétés ou classes qui ne sont plus jamais appelées.

Audit et nettoyage des dépendances (composer.json)

Passez en revue chaque bundle tiers :

• Le bundle est-il toujours maintenu ? Vérifiez sur GitHub ou Packagist. Si un bundle est abandonné et non compatible avec Symfony 6, il faudra trouver une alternative dès maintenant.
• Est-il vraiment utile ? Parfois, on installe un bundle pour une seule petite fonctionnalité que Symfony propose désormais nativement.
• Supprimez les paquets de développement inutiles : Nettoyez vos require-dev pour ne garder que l’essentiel (PHPUnit, PHPStan, etc.).

Nettoyage des Assets

Si vous utilisez Webpack Encore, vérifiez votre fichier package.json et supprimez les bibliothèques JS/CSS qui ne sont plus utilisées.

Étape 2 : Mise à jour de la version 5.4 (Dernière version mineure)

Avant de changer de version majeure, vous devez stabiliser votre application sur la toute dernière version de la branche 5.4. Cela permet de bénéficier de tous les derniers correctifs de bugs et, surtout, de disposer de tous les messages de dépréciation à jour.

Monter les composants Symfony au maximum

Modifiez votre fichier composer.json pour cibler la dernière version de la branche 5.4 pour tous les composants Symfony.

• Utilisez le wildcard 5.4.* pour forcer la mise à jour vers la version de maintenance la plus récente (ex: 5.4.35).
• Lancez la mise à jour :

composer update "symfony/*"

Mise à jour des bundles tiers

Il est vital de mettre à jour vos bundles externes (Doctrine, LexikJWT, NelmioApiDoc, etc.) vers leurs versions les plus récentes compatibles avec Symfony 5.4.

• Pourquoi ? Les mainteneurs de bundles publient souvent des versions qui supportent à la fois la 5.4 et la 6.0. Si un bundle est bloqué sur une vieille version, il pourrait empêcher le passage à Symfony 6 lors de l’étape 5.

Stabilisation de l’environnement

À la fin de cette étape, votre application doit être parfaitement fonctionnelle en 5.4. Ne passez pas à l’étape suivante tant que vos tests actuels (même s’ils affichent des alertes de dépréciation) ne sont pas au vert.

Étape 3 : Migration vers php 8.1+

Cette étape doit être réalisée alors que vous êtes encore sous Symfony 5.4. L’avantage est que la version 5.4 est totalement compatible avec les versions récentes de PHP, ce qui vous permet d’isoler les problèmes liés au langage avant de toucher au framework.

Mise à jour de l’environnement

Mettez à jour PHP sur votre machine de développement, vos environnements de CI (GitHub Actions, GitLab CI) et vos serveurs de recette/production.

Adaptation du composer.json

Indiquez explicitement à Composer la version de PHP que vous ciblez pour qu’il puisse vérifier la compatibilité des futurs paquets :

"require": {
    "php": ">=8.1.0",
    ...
}

Correction des ruptures de compatibilité PHP

Le passage à PHP 8.x apporte des changements majeurs (BC Breaks) qui pourraient casser votre code métier :

• Les types internes : PHP 8 est plus strict. Une fonction interne qui recevait null au lieu d’une string pourrait désormais lever une erreur fatale.
• Signature des méthodes : Si vous implémentez des interfaces de librairies tierces ou de PHP, vérifiez que vos signatures de méthodes (types d’arguments et de retour) correspondent exactement.

Exploitation des nouvelles fonctionnalités (Optionnel)

C’est le moment idéal pour moderniser votre code source grâce aux outils automatisés :

• Rector : Lancez Rector avec le set PHP_8X pour adapter votre code à php 8
• Attributes : Commencez à migrer vos annotations Doctrine ou Symfony (type @Route) vers les Attributs PHP 8 (ex: #[Route(…)]).

Validation

Une fois PHP mis à jour, relancez votre suite de tests. Si tout est “vert” en 5.4 sous PHP 8.1+, vous avez fait un grand pas vers symfony 6 mais aussi vous avez augmenté la qualité de votre projet.

Étape 4 : Traitement des dépréciations

C’est l’étape la plus fastidieuse, mais aussi la plus gratifiante. Symfony 6 est, par définition, Symfony 5.4 sans les couches de compatibilité. Si votre application tourne en 5.4 sans aucune dépréciation, la montée vers la 6.4 sera une simple formalité.

Identifier les dépréciations

Il est possible d’identifier vos dépréciations grace à :

• Le Profiler Symfony : Dans la barre d’outils (Web Debug Toolbar), vous pouvez retrouver facilement les dépréciations sur la page en cours.
• PHPUnit : C’est la méthode la plus fiable pour couvrir l’ensemble de votre code (même celui que vous ne voyez pas dans le navigateur). Lancez vos tests avec le système de SYMFONY_DEPRECATIONS_HELPER (suivant votre version de phpunit).

Automatiser avec Symfony Rector

Ne corrigez pas tout à la main ! Utilisez les sets Symfony_6X de Rector, qui sont des jeux de règles spécifiques pour Symfony. Il faut passer d’abord par les sets intermédiaires (SYMFONY_60, SYMFONY_61, etc.).

Exemple de correction de deprecations

1. Modernisation de la Sécurité

Le composant Security a été profondément remanié. L’ancien système (Guard) disparaît au profit d’authentificateurs plus simples.

• Interfaces : Remplacez UserPasswordEncoderInterface par UserPasswordHasherInterface.
• Modèles : Vos entités User doivent désormais implémenter PasswordAuthenticatedUserInterface (en plus de UserInterface).
• Configuration (security.yaml) : Remplacez la clé encoders par password_hashers.
• Accès : Dans votre access_control, remplacez le rôle IS_AUTHENTICATED_ANONYMOUSLY par l’attribut plus explicite PUBLIC_ACCESS.

2. Refactorisation des Tests (WebTestCase & PHPUnit)

La gestion du container et du cycle de vie du Kernel change dans les tests pour plus de clarté.

• Accès au container : Utilisez désormais static::getContainer() au lieu de l’ancien self::$container ou self::$kernel->getContainer().
• Cycle de vie : Plus besoin de forcer ensureKernelShutdown() manuellement avant chaque createClient().

Comparaison du setUp :

// AVANT (Déprécié)
public function setUp(): void {
    parent::setUp();
    self::bootKernel();
    self::ensureKernelShutdown();
    $this->client = self::createClient();
    $this->entityManager = self::$kernel->getContainer()->get('doctrine.orm.entity_manager');
}

// APRÈS (Standard Symfony 6)
public function setUp(): void {
    parent::setUp();
    $this->client = self::createClient();
    // Utilisation du container statique typé
    $this->entityManager = static::getContainer()->get(EntityManagerInterface::class);
}

3. Évolution de la configuration YAML

Quelques conventions d’écriture ont été simplifiées ou normalisées :

• Routes : Pour appeler une méthode de contrôleur, utilisez le double colon (::) au lieu du simple (:).
  • Avant : App\Controller\SecurityController:login
  • Après : App\Controller\SecurityController::login
• Doctrine Events : Privilégiez les doctrine.event_listener plutôt que les event_subscriber qui sont plus lourds et moins explicites sur les événements écoutés.

# Nouvelle syntaxe recommandée pour les Listeners
App\EventListener\XListener:
    tags:
        - { name: doctrine.event_listener, event: postPersist, connection: 'default' }

Finalisation

À la fin de cette étape, votre application tourne toujours en 5.4, mais votre console de test doit afficher “0 deprecations”.

Étape 5 : Bascule vers Symfony 6.4

Une fois que votre application tourne en 5.4 sous PHP 8.1+ sans aucune dépréciation, le changement de version devient une simple mise à jour de dépendances.

Modification du composer.json

Il est temps de changer les contraintes de version. Vous devez modifier toutes les bibliothèques symfony/* pour cibler la version 6.4.*, ainsi que la partie extra:

{
    ...
    "require": {
        ...
        "symfony/config": "6.4.*",
        "symfony/dotenv": "6.4.*",
        "symfony/serializer": "6.4.*",
        ...
    },
    "require-dev": {
        ...
        "symfony/browser-kit": "6.4.*",
        "symfony/css-selector": "6.4.*",
        "symfony/debug-bundle": "6.4.*",
        ...
    },
    "extra": {
        "symfony": {
            ...
            "require": "6.4.*",
            ...
        }
    }
    ...
}

Lancement de la mise à jour

Lancez la mise à jour globale :

composer update symfony/*

Nettoyage du Cache

Même si Composer le fait souvent, un nettoyage manuel est parfois nécessaire pour purger les conteneurs compilés de la version 5.4 :

php bin/console cache:clear

Étape 6 : Phase de tests et validation

Félicitations, votre application tourne désormais sous Symfony 6.4 ! Cependant, une migration réussie ne s’arrête pas à un composer update qui passe. Il faut maintenant valider la stabilité du projet et s’assurer qu’aucune régression ne s’est glissée dans votre logique métier.

La Checklist de Validation

• Analyse Statique (PHPStan/Psalm) : Le passage à PHP 8.1+ et Symfony 6 renforce le typage. Relancez votre analyseur statique pour détecter les incohérences de types au plus tôt avant de les avoir en production.
• Tests Unitaires : Exécutez l’intégralité de votre suite de tests. C’est le moment de vérifier que les changements internes du framework n’ont pas modifié le comportement de vos services.
• Tests d’Intégration : Vérifiez les flux complets, particulièrement les services qui dépendent de librairies tierces (API, envoi d’emails, Messenger).
• Analyse du Schéma : Utilisez la commande php bin/console doctrine:schema:validate. Elle doit confirmer que votre mapping est synchrone avec l’état actuel de votre base de données.
• Tests Manuels (Audit du Profiler) : Naviguez sur les pages critiques de votre application et surveillez l’onglet “Performance” et “Security” du Profiler pour détecter tout comportement anormal.

Conclusion

Migrer de Symfony 5.4 à 6.4 est bien plus qu’une simple mise à jour technique : c’est un véritable investissement sur la pérennité de votre application. En franchissant ce pas, vous avez non seulement assaini votre base de code en éliminant la dette technique liée à PHP 7, mais vous avez également armé votre projet pour les défis à venir.

La clé d’une migration réussie réside dans la rigueur de l’étape 4 (dépréciations). Un projet sans message d’alerte est un projet sain, performant et agréable à maintenir.

Liens utiles

• Documentation officielle : Upgrading a Major Version : Le guide de référence pour comprendre la philosophie et la procédure des montées de version Symfony.
• Symfony Roadmap : Pour suivre les dates de fin de support (EOL) et planifier vos prochaines migrations.
• Symfony Backwards Compatibility Promise : Pour comprendre comment Symfony gère les changements cassants et l’importance des dépréciations.
• Rector - Symfony Rules : Le dépôt officiel des règles de refactorisation automatique pour passer de Symfony 5.4 à 6.4.