Dans le développement d’API avec Laravel, il est essentiel de garantir que les erreurs soient renvoyées au format JSON, assurant ainsi une communication cohérente avec les clients front-end. Traditionnellement, cela nécessitait l’utilisation d’un middleware personnalisé pour forcer le header Accept à application/json.
Avec Laravel 11, une nouvelle méthode shouldRenderJsonWhen() a été introduite, permettant de définir globalement les conditions dans lesquelles les exceptions doivent être rendues en JSON. Cette méthode s’intègre directement dans la configuration de l’application, éliminant le besoin de middleware supplémentaire.
Par exemple, en modifiant le fichier bootstrap/app.php, on peut spécifier que toutes les requêtes vers des routes commençant par api/ renverront les exceptions au format JSON :
// bootstrap/app.php
return Application::configure(basePath: dirname(__DIR__))
//...
->withExceptions(function (Exceptions $exceptions) {
$exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
if ($request->is('api/*')) {
return true;
}
return $request->expectsJson();
});
})->create();Cette approche présente plusieurs avantages. Elle simplifie la gestion des erreurs en centralisant la logique de rendu des exceptions, assurant ainsi une réponse JSON cohérente pour les clients API, même lorsque le header Accept n’est pas explicitement défini. Cela est particulièrement utile lors des tests via un navigateur, où les requêtes peuvent ne pas inclure ce header.
Cependant, il est important de noter que cette configuration n’affecte que le rendu des exceptions. Les réponses réussies (statut HTTP 200) doivent toujours être explicitement retournées au format JSON dans les contrôleurs ou les routes.
En résumé, la méthode shouldRenderJsonWhen() introduite dans Laravel 11 offre une solution élégante pour assurer que les exceptions des API soient toujours retournées au format JSON, améliorant ainsi la cohérence et la maintenabilité du code. Cette fonctionnalité réduit la nécessité de middleware personnalisés et centralise la logique de gestion des erreurs, facilitant le développement d’API robustes.
Sources
- Paul Redmond - Always Render API Exceptions as JSON in Laravel