Une page qui liste des commandes avec le nom du client associé fonctionne parfaitement en local avec dix lignes de seed, puis s'effondre en production dès que la table dépasse quelques milliers d'enregistrements. Le temps de réponse grimpe presque linéairement avec le nombre de lignes affichées, alors que la requête SQL visible dans le contrôleur paraît tout à fait raisonnable. Le problème n'est presque jamais la requête que vous avez écrite, mais celles qu'Eloquent génère discrètement à votre place pendant le rendu de la vue.
Le mécanisme : pourquoi Eloquent multiplie les requêtes
Eloquent charge les relations en lazy loading par défaut. Quand vous accédez à $order->customer, le modèle ne possède pas encore cette donnée : la méthode magique __get intercepte l'accès, détecte qu'il s'agit d'une relation non chargée, et déclenche une requête SQL immédiate pour la récupérer. Tant que cet accès a lieu une seule fois, ce n'est pas un problème. Le problème survient quand cet accès se produit à l'intérieur d'une boucle.
// OrderController.php
public function index()
{
$orders = Order::latest()->paginate(20);
return view('orders.index', ['orders' => $orders]);
}
{{-- orders/index.blade.php --}}
@foreach ($orders as $order)
<tr>
<td>{{ $order->id }}</td>
<td>{{ $order->customer->name }}</td>
<td>{{ number_format($order->total_cents / 100, 2) }} €</td>
</tr>
@endforeach
Ce code exécute une requête pour récupérer les 20 commandes, puis une requête supplémentaire par ligne pour récupérer le client associé, soit 21 requêtes au lieu d'une poignée. Avec une pagination à 50 lignes et deux ou trois relations consommées dans la vue (client, adresse de livraison, dernier paiement), on atteint vite 150 requêtes sur une seule page, chacune avec sa latence réseau vers la base de données. En local, sur une base SQLite en mémoire ou un MySQL sur le même hôte, cette latence est négligeable. En production, avec une base distante et un pool de connexions sous charge, elle devient le facteur dominant du temps de réponse.
Diagnostiquer avant de corriger
Avant de corriger quoi que ce soit, il faut mesurer. Trois outils complémentaires :
Laravel Telescope ou Laravel Debugbar en environnement de développement affichent le nombre exact de requêtes exécutées par page et leur contenu. Une page qui affiche "47 queries" pour une liste de 20 éléments est un signal immédiat.
DB::listen permet un diagnostic rapide sans installer de package, utile en pair debugging ou pour instrumenter temporairement un environnement de staging :
DB::listen(function ($query) {
Log::debug($query->sql, $query->bindings);
});
Model::preventLazyLoading(), disponible depuis Laravel 10, transforme le problème en échec explicite plutôt qu'en lenteur silencieuse. Placé dans le boot() du AppServiceProvider et activé hors production, il lève une LazyLoadingViolationException dès qu'une relation non chargée est accédée :
// AppServiceProvider.php
public function boot(): void
{
Model::preventLazyLoading(! $this->app->isProduction());
}
Cette ligne, à elle seule, transforme chaque N+1 latent en échec de test ou en erreur 500 immédiate pendant le développement, bien avant qu'un client ne la découvre en scrollant une liste de commandes trop lentement.
La correction : eager loading ciblé
La correction consiste à indiquer à Eloquent, avant la boucle, quelles relations seront nécessaires, pour qu'il les récupère en une seule requête supplémentaire via une clause WHERE IN.
public function index()
{
$orders = Order::with('customer')->latest()->paginate(20);
return view('orders.index', ['orders' => $orders]);
}
On passe ainsi de 21 requêtes à 2 : une pour les commandes, une pour tous les clients concernés via SELECT * FROM customers WHERE id IN (...). Pour des relations imbriquées, la notation en points fonctionne :
$orders = Order::with('customer.address', 'latestPayment')->latest()->paginate(20);
Et si la vue n'affiche qu'un sous-ensemble des colonnes du client, restreindre les colonnes chargées réduit la quantité de données transférées, à condition d'inclure explicitement la clé étrangère :
$orders = Order::with(['customer:id,name'])->latest()->paginate(20);
Pour un besoin ponctuel sur une collection déjà récupérée (par exemple après un filtrage conditionnel en mémoire), loadMissing() est préférable à load() : il ne recharge que les relations pas encore présentes, évitant une requête redondante si elles ont déjà été chargées plus haut dans la pile d'appels.
Les compromis de l'eager loading systématique
Ajouter with() partout n'est pas une solution universelle. Trois pièges fréquents :
Le sur-chargement par défaut. Définir une propriété protected $with = ['customer'] directement sur le modèle Order force le chargement de cette relation sur tous les usages du modèle, y compris ceux qui n'en ont pas besoin (un job de facturation qui ne lit que le montant, par exemple). Préférer un eager loading explicite par cas d'usage, au niveau du contrôleur ou du repository, garde le contrôle fin sur ce qui est réellement nécessaire.
La duplication de lignes avec les relations hasMany. Contrairement à belongsTo (une commande a un seul client), charger une relation hasMany ou belongsToMany dans une collection paginée ne duplique pas les lignes PHP grâce au regroupement interne d'Eloquent, mais le volume de données transférées peut rester élevé si la relation contient beaucoup d'enregistrements par parent. Dans ce cas, withCount() pour un simple décompte, ou une sous-requête dédiée, coûte souvent moins cher que de charger la collection entière pour n'en afficher que la taille.
Le coût sur les exports volumineux. Pour un export de 100 000 lignes, paginate() avec eager loading reste correct, mais with() combiné à chunk() ou cursor() demande d'être vérifié : cursor() ne fonctionne pas nativement bien avec with() sur des relations hasMany en raison du hydratage ligne par ligne. Dans ce cas, chunk() ou lazy() avec eager loading explicite est le choix le plus sûr.
Quand l'eager loading simple ne suffit pas
Certains N+1 résistent à un simple with() :
Les relations polymorphiques. Un modèle Activity avec une relation morphTo() vers Order, Invoice ou Payment génère, même avec with('subject'), une requête par type polymorphique rencontré. La solution est morphWith(), qui précise les relations à eager-charger pour chaque type concret :
$activities = Activity::with(['subject' => function ($morphTo) {
$morphTo->morphWith([
Order::class => ['customer'],
Invoice::class => ['client'],
]);
}])->get();
Les accessors qui cachent une requête. Une méthode getStatusLabelAttribute() qui appelle $this->latestPayment->status déclenche un N+1 invisible dans le code du contrôleur et de la vue, car il se niche dans la définition du modèle. Telescope le révèle, une simple lecture du contrôleur non. La correction passe par l'eager loading de latestPayment en amont, combinée à une vérification whenLoaded dans l'accessor pour éviter un fallback silencieux vers le lazy loading en cas d'oubli.
Les API Resources. Une OrderResource utilisée en collection (OrderResource::collection($orders)) répète la même logique de boucle que Blade, mais la responsabilité du eager loading remonte alors au contrôleur, pas à la resource elle-même, qui ne doit idéalement contenir aucune requête.
Pour les volumes vraiment critiques (tableaux de bord agrégés sur des millions de lignes), l'eager loading ORM atteint ses limites structurelles : chaque requête supplémentaire reste un aller-retour réseau. Une vue SQL dénormalisée, une table d'agrégats rafraîchie périodiquement, ou une réplique de lecture dédiée aux requêtes analytiques, deviennent alors plus pertinents qu'un empilement de with().
En bref
Le N+1 n'est pas un bug ponctuel à corriger une fois pour toutes : c'est un risque structurel à chaque fois qu'une relation est consommée dans une boucle, qu'il s'agisse d'une vue Blade, d'un accessor ou d'une resource API. Activer Model::preventLazyLoading() en développement et dans les tests transforme ces fuites silencieuses en échecs immédiats et reproductibles, bien avant qu'un client ne les découvre en production sous forme de page qui met huit secondes à charger.
