Comprendre l'architecture hexagonale avec Symfony

Le problème que l'architecture hexagonale résout

Dans un projet Symfony classique, il est facile de laisser la logique métier fuiter dans les contrôleurs, les entités Doctrine ou les services couplés directement au framework. Résultat : un code difficile à tester unitairement, et une dépendance forte à l'infrastructure (base de données, SOAP, API tierces). L'architecture hexagonale — aussi appelée ports & adapters — propose de séparer strictement :

Le domaine métier, indépendant de tout framework
Les ports, des interfaces qui définissent les besoins du domaine
Les adapters, qui implémentent ces ports avec une technologie concrète (Doctrine, SOAP, REST, etc.)

Structure type

src/
├── Domain/
│   ├── Model/
│   └── Port/
├── Application/
│   └── UseCase/
└── Infrastructure/
    ├── Persistence/
    └── Http/

Le domaine ne connaît jamais Symfony, Doctrine ou une librairie HTTP. Il définit uniquement des interfaces (ports). L'infrastructure implémente ces interfaces.

Exemple concret : un port de persistance

Php

// Domain/Port/BeneficiaireRepositoryInterface.php
interface BeneficiaireRepositoryInterface
{
    public function findByNir(string $nir): ?Beneficiaire;
}

Php

// Infrastructure/Persistence/DoctrineBeneficiaireRepository.php
final class DoctrineBeneficiaireRepository implements BeneficiaireRepositoryInterface
{
    public function findByNir(string $nir): ?Beneficiaire
    {
        // logique Doctrine ici, invisible du domaine
    }
}

Le use case métier dépend uniquement de l'interface, jamais de l'implémentation Doctrine. Résultat : testable en isolation avec un simple mock ou un in-memory repository, sans base de données.

Bénéfices observés en pratique

Tests unitaires rapides sur la logique métier, sans bootstrap Symfony complet
Changement d'infrastructure facilité : remplacer un appel SOAP par une API REST devient un changement localisé à l'adapter, sans toucher au domaine
Séparation des responsabilités plus lisible pour les revues de code

Le vrai coût

Cette architecture ajoute de l'indirection et plus de fichiers pour des cas simples. Elle a du sens sur un cœur métier complexe et amené à durer, beaucoup moins sur un CRUD basique. Le juger au cas par cas plutôt que l'appliquer partout par principe.

En résumé

L'architecture hexagonale n'est pas une fin en soi, c'est un outil pour isoler la complexité métier des détails techniques. Sur un projet backend qui doit vivre plusieurs années et changer d'infrastructure au fil du temps, l'investissement initial se rentabilise rapidement.