Dans mon application Symfony, une nouvelle fonctionnalité finissait souvent répartie entre un contrôleur, une entité, un dépôt et un service. Cette organisation par type technique était facile à comprendre au départ. En grandissant, le dossier Service a rassemblé des règles métier sans rapport, les contrôleurs ont commencé à prendre des décisions et un changement de prestataire de paiement touchait plusieurs zones du code.
Le problème s’est posé dans Leganews, une plateforme d’information juridique que j’ai cofondée. Le produit avait déjà des utilisateurs et des données historiques. La refonte devait donc préserver le comportement existant pendant le déplacement du code.
J’ai rendu les frontières métier visibles et isolé le domaine de Symfony et Doctrine. Cette séparation n’a pas supprimé le coût de la migration, mais elle a réduit la portée des changements suivants.
L’implémentation combine Clean Architecture, Domain-Driven Design, injection de dépendances Symfony, Messenger, mappings Doctrine externes et Deptrac. Je détaille la structure et les contrôles qui la rendent vérifiable.
Cette structure n’a rien de mauvais en soi. Symfony fournit des choix par défaut pertinents, souvent suffisants pour une petite application.
Le problème apparaît lorsque le produit couvre plusieurs domaines métier. Une modification de la facturation peut être répartie entre Controller, Entity, Repository et Service. L’arborescence indique quel outil technique une classe utilise, mais pas à quelle capacité métier elle appartient.
À mesure que la plateforme grandissait, le code devait permettre de répondre à des questions plus utiles :
Cette partie relève-t-elle de l’identité, de la facturation, du suivi ou du corpus juridique ?
Quelles règles relèvent du métier et lesquelles ne sont que des détails propres à Doctrine ou Symfony ?
La facturation peut-elle évoluer sans casser accidentellement le suivi ?
Un cas d’usage peut-il être testé sans base de données ni requête HTTP ?
C’est à ce stade que le DDD et la Clean Architecture me sont devenus utiles.
Le Domain-Driven Design m’aide à organiser le système autour du langage et des frontières du métier. Au lieu d’un grand modèle applicatif unique, je définis des contextes bornés comme Identity, Billing, Access, Corpus et Monitoring.
La Clean Architecture dirige les dépendances du code source vers les règles métier, jamais dans le sens inverse.
Dans mon implémentation, leur direction se présente ainsi :
Mermaid
Le principe est simple :
Domain contient les concepts et les règles métier.
Application coordonne les cas d’usage.
Infrastructure implémente les détails techniques comme Doctrine, Redis et les API externes.
Presentation transforme les entrées HTTP ou console en messages applicatifs.
Le domaine ignore l’existence de Symfony, Doctrine, PostgreSQL et Redis.
Désormais, le code des signets se trouve principalement dans Monitoring. La structure des dossiers exprime le langage du produit avant les détails du framework.
Shared n’accueille pas ce que je ne sais pas classer. Il contient uniquement les concepts communs à plusieurs contextes. Une classe qui emploie le langage du produit appartient probablement à un contexte borné.
Dans un projet Symfony standard, Kernel.php se trouve directement sous src/. Je l’ai déplacé vers :
Plain text
src/Shared/Infrastructure/Framework/Kernel.php
Ce déplacement ne crée pas une Clean Architecture par magie. Il rend une décision visible. Symfony démarre l’application depuis l’infrastructure, mais ne se trouve pas au centre du modèle métier.
Puisque la classe a changé d’emplacement, les points d’entrée HTTP et console importent son nouvel espace de noms.
La même importation est utilisée dans bin/console.
Le chargement automatique de Composer reste simple :
JSON
{"autoload":{"psr-4":{"Leganews\\":"src/"}}}
Le déplacement du Kernel reste facultatif. La règle de dépendance compte davantage. Dans mon cas, ce déplacement l’a rendue visible et plus difficile à oublier.
La Clean Architecture n’impose pas d’éviter Symfony. Elle consiste à utiliser Symfony aux extrémités et à dépendre de contrats en allant vers le centre.
Ma configuration principale des services enregistre automatiquement les classes des couches Application, Infrastructure et Presentation :
Pourquoi exclure les entités et les objets-valeurs ? Parce qu’il s’agit d’objets du domaine, et non de services du conteneur. Ils doivent être créés par le domaine ou l’application à partir de données explicites, plutôt que récupérés dans le conteneur de Symfony.
Lorsque l’autowiring est activé, un handler peut dépendre d’une interface du domaine :
La couche Application ne demande ni EntityManagerInterface ni un dépôt Doctrine. Elle dépend du port métier BookmarkRepository.
Lorsqu’il n’existe qu’une implémentation, Symfony peut la résoudre sans qu’il soit nécessaire d’ajouter des alias répétitifs. Dans mon application, par exemple, le conteneur résout :
Mermaid
Lorsque plusieurs implémentations existent, la configuration en sélectionne une. Ma passerelle de paiement possède un adaptateur en mémoire et un adaptateur FlexPay. L’application reçoit celui choisi pour l’environnement.
Ce code ne contient ni contrôleur, ni requête HTTP, ni gestionnaire d’entités, ni attribut Doctrine.
Je transmets également l’heure actuelle au domaine. L’entité n’appelle pas new DateTimeImmutable() pour déterminer l’instant présent. Le temps devient ainsi explicite et contrôlable dans les tests.
Cette interface n’est pas une abstraction ajoutée "au cas où". Un cas d’usage réel exige ce port. Le domaine possède son langage et l’Infrastructure fournit l’implémentation.
Doctrine dépend de la classe du domaine. La classe du domaine ne dépend pas de Doctrine. C’est cette direction qui importe.
Elle m’offre également un point de substitution utile pour les tests. Un test peut remplacer Doctrine par un petit dépôt en mémoire qui implémente la même interface.
Chaque contexte borné reçoit ensuite sa propre configuration de mapping Doctrine :
YAML
# config/packages/doctrine.yamldoctrine:orm:entity_managers:default:mappings:Monitoring:is_bundle:falsetype: xml
dir:'%kernel.project_dir%/config/doctrine/Monitoring'prefix:'Leganews\Monitoring\Domain\Model'Billing:is_bundle:falsetype: xml
dir:'%kernel.project_dir%/config/doctrine/Billing'prefix:'Leganews\Billing\Domain\Model'
Répétez le bloc de mapping pour les autres contextes.
Cette configuration est légèrement plus verbeuse que les attributs, mais elle maintient les métadonnées de persistance à la périphérie. Je peux lire et tester unitairement l’entité comme un objet PHP ordinaire.
La couche Application coordonne un cas d’usage. Elle ne contient pas de code HTTP et ne doit pas réimplémenter des règles déjà prises en charge par le domaine.
Le contrôleur est volontairement sans intérêt particulier. L’authentification, le mapping de la requête et la sérialisation de la réponse ont leur place ici. La décision concernant la création d’un signet, elle, n’y appartient pas.
J’utilise Symfony Messenger derrière mes propres contrats légers CommandBus, QueryBus, MessageBus et EventDispatcher.
Les adaptateurs Symfony se trouvent dans Infrastructure. Les handlers restent ainsi indépendants de l’API d’exécution de Messenger, tout en pouvant utiliser des attributs pratiques comme #[AsMessageHandler].
Les commandes modifient l’état, donc leur bus ajoute un middleware de transaction Doctrine. Les requêtes lisent l’état sans cette transaction. Le bus d’événements accepte l’absence de gestionnaire, car un fait peut n’avoir aucun abonné.
Le middleware de corrélation transmet un même identifiant tout au long de la chaîne de messages, ce qui facilite le suivi des journaux d’une opération complète.
Cette séparation n’est pas seulement stylistique. Elle donne un objectif clair à chaque message et me permet d’appliquer des politiques de middleware différentes selon les opérations.
Une convention de dossiers est utile jusqu’au jour où quelqu’un importe accidentellement Doctrine dans le domaine sans que la revue de code ne le détecte.
L’architecture doit être exécutable. J’utilise Deptrac pour décrire les dépendances autorisées :
La ligne importante est Domain: ~. Les classes du domaine ne peuvent dépendre ni d’une autre couche architecturale ni de l’environnement d’exécution de Symfony.
Je modélise volontairement les attributs Symfony à part. Un handler applicatif peut utiliser le marqueur passif #[AsMessageHandler] sans recevoir le bus de messages de Symfony comme dépendance d’exécution.
Exécutez le contrôle avec :
Bash
vendor/bin/deptrac --no-progress
Au moment de la rédaction, le projet ne signale aucune violation non ignorée. Je conserve également une liste skip_violations visible pour les dépendances acceptées, comme l’implémentation UUID de Symfony.
Cette liste compte. Une violation ignorée ne signifie pas que "l’architecture est parfaite". Elle documente un compromis à réexaminer au lieu de cacher la dépendance dans le code.
Mes règles actuelles imposent la direction globale des couches. Elles ne garantissent pas encore une isolation complète entre tous les contextes bornés. Par exemple, une classe du domaine d’un contexte peut encore référencer un objet-valeur du domaine d’un autre contexte sans que Deptrac ne le refuse.
Si votre système exige une isolation plus forte des contextes, ajoutez une couche par contexte ou utilisez des collecteurs supplémentaires. Commencez par des règles que votre équipe peut comprendre et maintenir, puis renforcez-les à mesure que les frontières se stabilisent.
Une contrainte a guidé cette architecture. Leganews possédait déjà des données dans une ancienne application MariaDB, tandis que la plateforme refactorisée utilise PostgreSQL.
Cette réécriture ne pouvait pas se limiter à améliorer la forme du code. Elle devait préserver les utilisateurs, le contenu juridique, les abonnements, les commandes, les signets et leurs relations.
J’ai isolé l’ancienne base de données dans une connexion Doctrine DBAL distincte :
L’ordre représente les dépendances entre les données. Les utilisateurs doivent exister avant leurs signets ; les produits et les prix avant les commandes ; les organisations avant les adhésions.
Chaque plan implémente un contrat de migration au niveau applicatif, tandis que SQL et la connaissance de l’ancien schéma restent dans Infrastructure. L’importateur prend en charge l’orchestration, les rapports, la gestion des conflits et les échecs de lignes.
Mermaid
J’ai également conservé les identifiants stables lorsque cela était possible. Cela a limité les références rompues pendant que le nouveau modèle introduisait des concepts et des frontières plus clairs.
J’ai ainsi obtenu une démarche de refactorisation concrète :
Modéliser une capacité métier dans son contexte borné.
Placer les nouveaux cas d’usage derrière des commandes et des requêtes applicatives.
Adapter la persistance et les systèmes externes à la périphérie d’Infrastructure.
Importer les données historiques dans l’ordre de leurs dépendances.
Vérifier les décomptes, les conflits et les lignes rejetées avant de basculer le trafic.
La leçon est que la Clean Architecture n’est pas seulement utile après une migration. Elle aide à créer une destination sûre vers laquelle migrer.
L’interface du dépôt permet à mes tests applicatifs de s’exécuter avec des adaptateurs en mémoire et une horloge contrôlable.
Un scénario de cas d’usage se présente ainsi :
Plain text
Scenario: Creating a bookmark starts a private collection
Given current time is "2026-07-13 10:00:00"
When a bookmark is created through the application with the following details:
| userId | name | description | visibility |
| ... | Research folder | | private |
Then the bookmark should keep the following presentation:
| name | visibility | updatedAt |
| Research folder | private | 2026-07-13 10:00:00 |
And the bookmark creation should be announced
Ce test utilise le véritable bus de commandes et le véritable handler, mais remplace la base de données par un dépôt en mémoire. Il vérifie la frontière applicative sans transformer chaque scénario métier en un test lent dans le navigateur.
J’utilise différents types de tests selon les risques :
PHPUnit pour les entités, les objets-valeurs, les politiques et les règles isolées du domaine.
Behat pour les commandes et les requêtes à la frontière applicative.
Les tests fonctionnels Symfony pour le routage, la sécurité, la sérialisation, les mappings Doctrine et les autres intégrations au framework.
Deptrac contrôle ensuite un aspect que les tests ne vérifient généralement pas : la validité de la direction des dépendances.
Une règle d’architecture exécutée uniquement sur la machine d’un développeur finira inévitablement par être contournée.
Ma commande de qualité regroupe le formatage, la validation de la configuration Symfony, l’analyse statique, une simulation Rector et Deptrac. Voici la partie liée à cet article :
Exécutez la commande d’architecture dans la CI à chaque modification. Une dépendance interdite doit provoquer un échec comme le ferait un test, et non susciter une discussion six mois plus tard.
Les fichiers sont plus nombreux, car les commandes, les handlers, les ports et les adaptateurs ont des responsabilités distinctes.
Les mappings Doctrine externes sont plus verbeux que les attributs d’entité.
L’équipe doit s’accorder sur le langage du domaine, sans quoi les contextes bornés deviennent de simples dossiers techniques mieux nommés.
Deptrac protège uniquement les règles configurées. Il ne peut pas déterminer si un concept métier appartient au bon contexte.
Toutes les opérations CRUD n’ont pas besoin d’un agrégat complexe ni d’un événement de domaine.
J’essaie de rester pragmatique. L’objectif n’est pas de multiplier les interfaces et les couches, mais de maintenir les décisions métier importantes indépendantes des détails d’exposition et de persistance.
Si un simple modèle de lecture peut répondre à une requête, je l’utilise. S’il n’existe qu’un seul adaptateur, je laisse Symfony le câbler automatiquement. Si j’accepte une exception architecturale, je la consigne explicitement au lieu de prétendre qu’elle n’existe pas.
La refactorisation de Leganews autour de la Clean Architecture et du DDD a transformé bien plus que l’arborescence des dossiers.
Les contextes bornés ont rendu visibles les responsabilités métier.
Les objets du domaine sont devenus de simples objets PHP aux règles explicites.
Les contrats des dépôts et des bus ont inversé les dépendances vers le cœur de l’application.
Le conteneur d’injection de dépendances de Symfony a assemblé l’implémentation aux extrémités.
Les mappings Doctrine externes ont maintenu les détails de l’ORM hors du domaine.
Messenger a attribué aux commandes, aux requêtes et aux événements des politiques d’exécution distinctes.
Deptrac a transformé l’intention architecturale en contrôle automatisé.
Les plans de migration ordonnés ont permis au nouveau modèle de coexister avec les données historiques pendant la refactorisation.
Le résultat n’est pas une application sans framework. C’est une application Symfony dans laquelle Symfony est employé délibérément, là où il est le plus efficace, sans devenir lui-même le modèle métier.
Je peux ainsi faire évoluer le système sans rendre chaque décision technique permanente.
Cette refonte n’a pas consisté à déplacer chaque classe vers un dossier au nom plus savant. Les contextes bornés ont regroupé le code par capacité métier. Les ports ont rendu les dépendances visibles. Les mappings Doctrine externes et Deptrac ont empêché le framework de revenir discrètement dans le domaine.
Le compromis reste réel. Cette structure ajoute des fichiers et demande une discipline d’équipe. Elle se justifie lorsque plusieurs domaines évoluent indépendamment et que le coût du couplage est déjà visible. Pour une petite application stable, l’organisation Symfony habituelle peut rester le meilleur choix.
