Migration Symfony 6 vers 7: Le guide complet (de 6.x à 7.x LTS)

La version 7.4 de Symfony sortie en nombre 2025 n’est pas une simple mise à jour de routine, c’est la version de maturité de la génération 7. En migrant de la 6.4 vers la 7.4, vous passez d’une base de code de transition à un environnement optimisé pour les fonctionnalités les plus récentes du framework.

Que votre application tourne actuellement sous Symfony 6.0 ou 6.4, ce guide vous accompagne étape par étape pour sécuriser votre montée de version. Nous aborderons les pré-requis d’infrastructure, le nettoyage du code legacy et les stratégies pour atteindre la version 7.4 LTS avec une dette technique minimale.

Voici pourquoi cette migration est stratégique pour votre application :

• Exigence PHP 8.2+ et exploitation de PHP 8.3 : Symfony 7.4 exige au minimum PHP 8.2. Cela signifie que votre projet bénéficie obligatoirement des Readonly Classes et des dernières nouveautés du langage. La 7.4 tire également pleinement profit de PHP 8.3 (constantes de classe typées, attribut #[Override]), garantissant une robustesse de typage inégalée.
• Modernisation radicale de l’expérience développeur (DX) : Cette version intègre de nouveaux composants majeurs comme AssetMapper, qui permet de se passer de Node.js et Webpack pour la gestion du front-end, simplifiant drastiquement votre stack technique et vos pipelines CI/CD.
• Nettoyage définitif de la dette technique : La version 7.x a supprimé toutes les couches de compatibilité qui encombraient la version 6.4. En passant en 7.4, vous travaillez sur un code “pur”, sans dépréciations cachées, ce qui facilite l’onboarding de nouveaux développeurs et améliore les performances d’exécution.
• Stabilité Long Terme (LTS) : Choisir la 7.4, c’est s’offrir la tranquillité d’esprit avec un support étendu jusqu’en novembre 2028 (bugs) et novembre 2029 (sécurité). C’est la version idéale pour les projets d’entreprise qui nécessitent une stabilité maximale sans devoir changer de version majeure tous les six mois.
• Pont direct vers Symfony 8 : Tout comme la 6.4 préparait à la 7, la version 7.4 est le miroir fonctionnel de la version 8.0. Réussir cette migration, c’est garantir que votre application est déjà techniquement prête pour la prochaine version majeure et le futur cycle de support du framework.

Sommaire de la migration

1. Étape 1 : Phase de nettoyage et d’audit
2. Étape 2 : Mise à jour de la version 6.4 (Dernière version mineure)
3. Étape 3 : Migration vers php 8.2+
4. Étape 4 : Traitement des dépréciations
5. Étape 5 : Bascule vers Symfony 7.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 6.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 6.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 6.4 pour tous les composants Symfony.

• Utilisez le wildcard 6.4.* pour forcer la mise à jour vers la version de maintenance la plus récente (ex: 6.4.36).
• 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 6.4.

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

Stabilisation de l’environnement

À la fin de cette étape, votre application doit être parfaitement fonctionnelle en 6.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.2+

Cette étape doit être réalisée alors que vous êtes encore sous Symfony 6.4. L’avantage est que la version 6.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.2.0",
    ...
}

Correction des ruptures de compatibilité PHP

Le passage à PHP 8.x apporte des changements majeurs qui pourraient casser votre code métier.

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

Validation

Une fois PHP mis à jour, relancez votre suite de tests. Si tout est “vert” en 6.4 sous PHP 8.2+, vous avez fait un grand pas vers symfony 7 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 7 est, par définition, Symfony 6.4 sans les couches de compatibilité. Si votre application tourne en 6.4 sans aucune dépréciation, la montée vers la 7.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_7X de Rector, qui sont des jeux de règles spécifiques pour Symfony. Il faut passer d’abord par les sets intermédiaires (SYMFONY_70, SYMFONY_71, etc.).

Exemple de correction de deprecations

1. La fin définitive des Annotations

C’est le plus gros morceau. Si vous utilisiez encore des annotations (ex: @Route, @Assert), elles ne sont plus supportées.

• Correction : Vous devez basculer intégralement sur les Attributs PHP 8.
• Exemple : #[Route('/path', name: 'route_name')] au lieu de /** @Route(...) */.

2. Typage strict des paramètres

Symfony 7 a ajouté des types de retour et des types de paramètres natifs PHP partout dans ses interfaces.

• Le problème : Si vous surchargez une méthode de Symfony (par exemple dans un UserProvider ou un EventListener), votre signature doit correspondre exactement à celle de Symfony 7 (qui inclut désormais des types comme string, int, void ou des types d’objets précis).
• Correction : L’outil Rector est presque indispensable ici pour ajouter automatiquement ces types dans votre code.

3. Le passage au nouveau système de Commandes

La signature de la méthode execute() des commandes Symfony a été figée.

• Correction : Assurez-vous que votre méthode execute retourne bien un int (en utilisant les constantes Command::SUCCESS ou Command::FAILURE) et que les types des arguments InputInterface et OutputInterface sont bien présents.

4. Injection ciblée des Normalizers

L’autowiring des Normalizers a été affiné pour éviter les ambiguïtés dans le Serializer.

• Le problème : L’injection directe du ObjectNormalizer peut poser problème si plusieurs normalizers sont enregistrés ou si vous tentez de décorer le service.
• Correction : Utilisez l’attribut #[Autowire] pour cibler précisément le service souhaité, garantissant que vous utilisez le bon moteur de normalisation.
• Exemple : #[Autowire(service: 'serializer.normalizer.object')] private NormalizerInterface $normalizer

5. Paramètres de configuration obligatoires (framework.yaml)

Symfony 7.4 impose de définir explicitement certains comportements qui étaient auparavant optionnels ou implicites.

• Le problème : L’absence des clés http_method_override et handle_all_throwables dans votre configuration générera une erreur lors de la compilation du container.
• Correction : Ajoutez ces paramètres dans votre fichier config/packages/framework.yaml.

6. Suppression de enable_authenticator_manager

Le “nouveau” système de sécurité (introduit en 5.3) est désormais le seul et unique système disponible.

• Le problème : La clé enable_authenticator_manager: true dans le paramétrage security est devenue obsolète puis a été supprimée, car ce mode est désormais natif et non désactivable.
• Correction : Supprimez simplement cette ligne de votre fichier security.yaml. Si votre configuration n’était pas encore compatible avec ce gestionnaire, vous devrez refactoriser vos authenticators (Guard vers Authenticator).

Finalisation

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

Étape 5 : Bascule vers Symfony 7.4

Une fois que votre application tourne en 6.4 sous PHP 8.2+ 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 7.4.*, ainsi que la partie extra:

{
    ...
    "require": {
        ...
        "symfony/config": "7.4.*",
        "symfony/dotenv": "7.4.*",
        "symfony/serializer": "7.4.*",
        ...
    },
    "require-dev": {
        ...
        "symfony/browser-kit": "7.4.*",
        "symfony/css-selector": "7.4.*",
        "symfony/debug-bundle": "7.4.*",
        ...
    },
    "extra": {
        "symfony": {
            ...
            "require": "7.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 6.4 :

php bin/console cache:clear

Étape 6 : Phase de tests et validation

Félicitations, votre application tourne désormais sous Symfony 7.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 à Symfony 7.4 impose une rigueur de typage accrue. Avec l’arrivée des types DNF et des Readonly Classes, vos analyseurs détecteront des erreurs de variance ou d’initialisation que Symfony 6.4 tolérait encore. C’est l’étape cruciale pour garantir la robustesse de votre code sous PHP 8.2+.
• Tests Unitaires : Exécutez l’intégralité de votre suite de tests. Symfony 7 ayant supprimé toutes les méthodes dépréciées de la branche 6, c’est le seul moyen de garantir que votre logique métier n’appelle pas de fonctions désormais inexistantes dans le noyau du framework.
• Tests d’Intégration : Vérifiez les flux complets, en portant une attention particulière au composant AssetMapper ou au nouveau Scheduler si vous les avez adoptés. Assurez-vous que vos interactions avec les API et Messenger respectent les nouvelles signatures de méthodes de la v7.
• Analyse du Schéma : Utilisez la commande php bin/console doctrine:schema:validate. Elle est cruciale ici pour confirmer que vos Attributs PHP (qui remplacent définitivement les annotations) sont correctement mappés et que votre base de données est en parfaite adéquation avec vos entités Symfony 7.
• Tests Manuels (Audit du Profiler) : Naviguez sur les pages critiques et surveillez le Profiler, notamment l’onglet “Events” et “Performance”. La version 7.4 introduit des optimisations dans le cycle de vie des requêtes. Assurez-vous qu’aucun listener personnalisé ne crée d’effets de bord inattendus.

Conclusion

Passer à Symfony 7.4, c’est choisir une architecture moderne et épurée. Ce saut technologique vous permet d’éliminer les dernières dépréciations de la version 6.4 et d’exploiter pleinement la puissance de PHP 8.2. En adoptant cette version LTS, vous offrez à votre projet un horizon de maintenance serein jusqu’en 2029.

La clé d’une migration réussie réside dans l’élimination totale des dépréciations avant le saut final. Un projet en 7.4 sans message d’alerte est un projet robuste, moderne et virtuellement prêt pour Symfony 8.

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 : L’outil indispensable pour automatiser la mise à jour de vos types et la suppression des méthodes obsolètes entre la 6.4 et la 7.4.