Une application Symfony qui répond en 200ms avec dix lignes en base et qui met trois secondes avec dix mille lignes n'a presque jamais un problème de base de données - elle a un problème d'utilisation de Doctrine. L'ORM masque volontairement la complexité des requêtes SQL sous-jacentes, ce qui est précisément ce qui permet à un code fonctionnellement correct de devenir silencieusement catastrophique en performance dès que le volume de données augmente. Les causes sont presque toujours les mêmes : requêtes N+1, hydratation surdimensionnée, et flush() appelé sans discernement dans une boucle.

Le problème N+1 : le classique increvable

Le symptôme est toujours le même : une liste de 50 éléments déclenche 51 requêtes SQL au lieu d'une ou deux.

// Déclenche 1 requête pour récupérer les commandes,
// puis 1 requête SUPPLÉMENTAIRE par commande pour charger son client
$orders = $em->getRepository(Order::class)->findAll();

foreach ($orders as $order) {
    echo $order->getCustomer()->getName(); // requête lazy à chaque itération
}

Le mécanisme sous-jacent est celui des proxies et du chargement différé (lazy loading). Par défaut, une relation ManyToOne ou OneToMany n'est pas chargée avec l'entité principale : Doctrine génère un proxy qui ne déclenche la requête SQL réelle qu'au premier accès à une propriété de l'entité liée. C'est un bon compromis par défaut (on ne charge pas ce qu'on n'utilise pas), mais désastreux dès qu'une boucle accède systématiquement à la relation.

// Correction : jointure explicite avec addSelect pour tout charger en une requête
$orders = $em->createQueryBuilder()
    ->select('o', 'c')
    ->from(Order::class, 'o')
    ->leftJoin('o.customer', 'c')
    ->getQuery()
    ->getResult();

Le mécanisme sous-jacent : Unit of Work et identity map

Doctrine maintient en mémoire un Unit of Work qui suit chaque entité gérée (managée) et calcule, au moment du flush(), l'ensemble des changements à persister en comparant l'état actuel de chaque entité à l'état connu au moment de son chargement. Chaque entité chargée reste référencée dans l'identity map pendant toute la durée de vie de l'EntityManager. Ce mécanisme est ce qui permet à Doctrine de garantir qu'une même ligne de base ne donne jamais deux objets PHP différents dans la même requête HTTP - mais il a un coût mémoire et CPU qui croît avec le nombre d'entités chargées, et ce coût est invisible tant qu'on ne regarde pas spécifiquement le nombre de requêtes générées ou le temps d'hydratation.

Diagnostiquer avant d'optimiser à l'aveugle

Le Symfony Profiler (panneau Doctrine) donne immédiatement le nombre de requêtes exécutées par page - un nombre qui croît avec le volume de données plutôt que de rester constant est le signal N+1 par excellence. Pour aller plus loin :

// Activer temporairement le logger SQL pour inspecter les requêtes générées
$em->getConnection()->getConfiguration()->setSQLLogger(
    new \Doctrine\DBAL\Logging\DebugStack()
);
-- Vérifier qu'un index existe réellement sur la clé étrangère utilisée dans les jointures
EXPLAIN ANALYZE
SELECT o.*, c.* FROM orders o
LEFT JOIN customers c ON c.id = o.customer_id
WHERE o.status = 'pending';

Un EXPLAIN ANALYZE qui révèle un Seq Scan sur une table de plusieurs centaines de milliers de lignes, là où un Index Scan était attendu, indique généralement un index manquant sur la colonne de jointure ou de filtre - un problème qui existe indépendamment de Doctrine, mais que l'ORM a tendance à masquer puisqu'il génère la requête pour vous.

Le correctif, avec ses compromis

Le fetch join (leftJoin + addSelect) résout le N+1, mais introduit un piège symétrique : joindre plusieurs collections OneToMany dans la même requête provoque une explosion cartésienne de lignes dupliquées avant hydratation, ce qui peut être pire que le N+1 initial pour des collections volumineuses. La bonne pratique est de limiter le fetch join à une seule collection à la fois, et de recourir à un second appel (ou à une pagination applicative) pour les relations suivantes.

// Pagination correcte avec jointure : utiliser le Paginator de Doctrine,
// pas un simple setMaxResults sur une requête avec jointure one-to-many
use Doctrine\ORM\Tools\Pagination\Paginator;

$query = $em->createQueryBuilder()
    ->select('o', 'items')
    ->from(Order::class, 'o')
    ->leftJoin('o.items', 'items')
    ->getQuery();

$paginator = new Paginator($query);
$paginator->setUseOutputWalkers(false); // à ajuster selon la requête, cf. doc Doctrine
$total = count($paginator);

Pour les listes en lecture pure (API de reporting, export, écran de consultation), l'hydratation en tableau (->getQuery()->getArrayResult()) ou en objets partiels évite de construire des entités complètes avec tout leur graphe de proxies, ce qui réduit significativement le coût CPU et mémoire quand aucune modification n'est prévue sur ces données.

Quand flush() en boucle devient le vrai goulot

// Anti-pattern : flush() dans la boucle recalcule le changeset
// de TOUTES les entités managées à chaque itération
foreach ($rows as $row) {
    $product = new Product();
    $product->setName($row['name']);
    $em->persist($product);
    $em->flush(); // coût croissant : O(n) par appel, O(n²) sur l'ensemble de la boucle
}

Chaque appel à flush() déclenche un calcul de changeset sur l'ensemble des entités actuellement managées par l'EntityManager, pas seulement sur celle qu'on vient de modifier. Pour un import de dix mille lignes, le coût cumulé devient quadratique plutôt que linéaire, parce que l'identity map grossit à chaque itération sans jamais être vidée.

// Correctif : flush groupé, avec clear() périodique pour libérer l'identity map
foreach ($rows as $i => $row) {
    $product = new Product();
    $product->setName($row['name']);
    $em->persist($product);

    if (($i + 1) % 200 === 0) {
        $em->flush();
        $em->clear(); // détache toutes les entités managées, libère la mémoire
    }
}
$em->flush();

Le compromis de clear() est qu'il détache toutes les entités, y compris celles dont on aurait encore besoin plus loin dans le traitement - ce qui impose de recharger explicitement toute entité réutilisée après un clear(), sous peine d'une EntityNotFoundException ou d'une entité détachée silencieusement incohérente.

Quand le correctif facile ne suffit pas

Pour un import massif (plusieurs centaines de milliers de lignes), même le flush() par lots reste trop coûteux : Doctrine construit des objets PHP complets avec tout leur cycle de vie (événements, listeners, validations) pour chaque ligne. À ce volume, une insertion en masse via DBAL directement ($connection->executeStatement() avec des requêtes INSERT multi-lignes) ou un chargement via COPY (PostgreSQL) contourne délibérément l'ORM, en acceptant de perdre les hooks de cycle de vie en échange d'un gain d'un ou deux ordres de grandeur sur le temps d'exécution.

Un autre cas limite, plus insidieux, concerne les processus longs (worker Symfony Messenger, commande CLI de traitement par lot) : l'identity map ne se vide jamais d'elle-même, donc un worker qui traite des milliers de messages sans jamais appeler $em->clear() périodiquement accumule des entités en mémoire jusqu'à épuiser la RAM disponible, un comportement qui n'apparaît qu'après plusieurs heures d'exécution continue et donc rarement en tests.

Enfin, cascade: ["remove"] combiné à orphanRemoval: true sur une relation OneToMany peut déclencher des suppressions en cascade non anticipées - chaque suppression individuelle d'une entité enfant génère sa propre requête DELETE, ce qui transforme une suppression a priori triviale en centaines de requêtes séquentielles sur une collection volumineuse.

À retenir

La performance avec Doctrine se gère en surveillant trois signaux précis - nombre de requêtes par page, taille de l'identity map en mémoire, et coût cumulé des flush() - plutôt qu'en optimisant des requêtes individuelles au hasard. Le fetch join, l'hydratation partielle et le clear() périodique couvrent la grande majorité des cas ; au-delà d'un certain volume, accepter de sortir de l'ORM pour les opérations de masse est un choix d'architecture légitime, pas un aveu d'échec.