Doctrine dans une montée Symfony : un calendrier qui n'est pas celui du framework
Mise à jour le 9 août 2026
La promesse de rétrocompatibilité de Symfony ne couvre que Symfony. Doctrine est un projet indépendant, avec ses propres versions majeures, ses propres ruptures et son propre rythme. Sur une application de gestion, la couche de persistance est aussi la plus couplée au code métier : c'est fréquemment elle, et non le framework, qui fixe la durée réelle d'une montée de version.
Où en est Doctrine ORM
| Ligne | Statut publié par le projet |
|---|---|
| ORM 4.0 | À venir |
| ORM 3.6 | Stable |
| ORM 2.20 | Stable |
| ORM 2.19 et antérieures | Non maintenues |
Source : la page du projet Object Relational Mapper, relevée le 9 août 2026. Deux lignes stables coexistent, la 2.20 et la 3.6, ce qui laisse une porte de sortie intermédiaire : passer d'une 2.x ancienne à 2.20 est une montée mineure, qui remet dans une version maintenue sans franchir la majeure. Tout ce qui est antérieur à 2.20 sur la branche 2 est déclaré non maintenu.
L'ordre recommandé par les mainteneurs eux-mêmes
Le document de montée du dépôt Doctrine ORM ne se contente pas de lister les ruptures, il donne une séquence. Plutôt que d'enchaîner plusieurs montées majeures, il recommande de passer à DBAL 3, de déployer et d'observer, puis de monter en ORM 3, de déployer et d'observer, puis seulement de passer à DBAL 4. La couche d'abstraction de base de données se traite donc avant l'ORM, pas en même temps.
Deux précisions du même document valent la peine d'être notées avant de planifier. Pour une application Symfony, la version minimale recommandée de Doctrine Bundle pour fonctionner avec ORM 3 est la 2.15 : le bundle d'intégration a donc son propre plancher, distinct de celui de l'ORM. Et le document recommande de passer à PHP 8.4 en premier, puis d'aller directement de l'ORM 2.19 à la 3.5 ou au-delà, afin de sauter une étape intermédiaire de génération de mandataires et d'utiliser directement les objets à chargement différé natifs du langage.
Les ruptures qui touchent le plus de code
La plus large, de loin, concerne le mapping. Le document de montée indique que le pilote d'annotations et tout ce qui s'y rapporte ont été retirés en 3.0, avec pour consigne de migrer vers un autre pilote. Le mouvement avait été annoncé longtemps à l'avance : le pilote d'annotations était déjà déprécié en 2.14, et la recommandation d'alors désignait les attributs natifs de PHP, disponibles depuis la version 8.0, comme la meilleure option. Une application dont les entités sont annotées doit donc être convertie avant de franchir la majeure, et cela touche l'intégralité de la couche de persistance.
Deux autres suppressions se remarquent vite. L'interface marqueur `Doctrine\ORM\Mapping\Annotation` a été remplacée par `Doctrine\ORM\Mapping\MappingAttribute`, ce qui casse les bibliothèques qui étendaient le système de mapping. Et `EntityManager::create()`, dépréciée dès la 2.13, a disparu en 3.0 : c'est une ligne dans un fichier d'amorçage, mais elle empêche l'application de démarrer.
Enfin, un détail opérationnel qui fait gagner du temps si on le connaît avant : le document signale, pour le code reposant sur les pilotes YAML, une commande `orm:convert-mapping` capable de convertir les métadonnées de mapping en XML avant la montée en 3.0. Faire cette conversion pendant que l'ancienne version fonctionne encore est beaucoup plus simple que de la faire après avoir cassé le démarrage.
Comment Doctrine signale ses dépréciations
Le mécanisme diffère de celui de Symfony, et cette différence est exploitable. Le même document explique que Doctrine s'appuie sur deux dispositifs : des blocs de documentation `@deprecated` que les environnements de développement et les outils d'analyse statique détectent, et une interface de dépréciation à l'exécution, portée par un paquet dédié.
La conséquence est intéressante. Une partie du signal Doctrine est statique : un analyseur la lit sans rien exécuter, et couvre donc aussi les chemins de code qu'aucun test ne parcourt. Là où les dépréciations Symfony ne se révèlent qu'à l'exécution, celles de Doctrine sont partiellement visibles à froid. Passer un analyseur statique sur le projet avant de commencer donne un premier inventaire, gratuit, sur la couche exacte qui risque de coûter le plus cher.
Questions fréquentes
Peut-on monter Symfony sans monter Doctrine ?
Souvent oui, dans la limite des contraintes de version que Doctrine Bundle déclare. Les deux projets ont des calendriers séparés, et rien n'oblige à les faire coïncider. Ce qui n'est pas recommandé, c'est de les monter dans la même livraison : vous perdriez la capacité d'attribuer une régression à l'un ou à l'autre, sur les deux couches les plus structurantes de l'application.
Faut-il convertir les annotations avant ou pendant la montée ?
Avant. La conversion des annotations vers les attributs se fait pendant que l'application fonctionne encore, ce qui permet de la livrer seule, de la vérifier et de la corriger sans le bruit d'une montée majeure par-dessus. Le pilote d'annotations ayant été retiré en 3.0, cette conversion est de toute façon un prérequis et non une option.
Rector aide-t-il sur la partie Doctrine ?
Le projet Rector maintient un jeu de règles dédié à Doctrine, référencé depuis son [dépôt principal](https://github.com/rectorphp/rector). Les mêmes réserves que sur la partie Symfony s'appliquent : il traite le volume mécanique et laisse ce qui demande une décision. Sur une conversion de mapping, la part mécanique est importante, ce qui en fait un des cas où l'outil rend le plus de service.
Faire auditer votre application Symfony
Réponse humaine sous 24 h ouvrées. Prendre contact ne vous engage à rien.
Symfony, Doctrine, Rector, Composer et PHP sont des projets et des marques appartenant à leurs détenteurs respectifs. Smartshift n'est ni affiliée, ni partenaire, ni mandatée par aucun d'eux. Les dates de fin de support citées proviennent des calendriers publics de ces projets, relevées le 9 août 2026 ; vérifiez-les avant toute décision engageante, elles peuvent évoluer.