Gestion des erreurs - Knowledge of Laravel

Aperçu

Lorsque vous créez un projet Laravel, la gestion des erreurs et des exceptions est déjà configurée par défaut. La personnalisation se fait via la méthode withExceptions dans bootstrap/app.php.

Flux de traitement des exceptions

Voici le cheminement d’une exception, de son déclenchement à la réponse renvoyée au client.

// bootstrap/app.php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions): void {
        // Configurez ici la reporting et le rendu des exceptions
    })->create();

L’objet $exceptions passé à la closure withExceptions est une instance de Illuminate\Foundation\Configuration\Exceptions qui pilote la gestion des exceptions dans toute l’application.

Configuration du mode debug

L’option debug de config/app.php contrôle le niveau de détail affiché pour les erreurs. Par défaut, sa valeur provient de la variable d’environnement APP_DEBUG du fichier .env.

# Développement local
APP_DEBUG=true

# Production
APP_DEBUG=false

En production, définissez impérativement APP_DEBUG sur false. Le laisser à true expose des informations sensibles à vos utilisateurs.

Signalement des exceptions

Signaler une exception, c’est l’enregistrer dans les logs ou l’envoyer à un service externe comme Laravel Nightwatch, Sentry ou Flare. Par défaut, Laravel enregistre les exceptions en s’appuyant sur la configuration de config/logging.php.

Callbacks de reporting personnalisés

Pour signaler certains types d’exceptions différemment, passez une closure à la méthode report. Laravel déduit le type d’exception depuis le type-hint de la closure.

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (InvalidOrderException $e) {
        // Notification à un service externe, etc.
    });
})

L’enregistrement dans les logs par défaut continue de fonctionner même lorsque vous enregistrez un callback personnalisé. Pour arrêter la propagation vers la gestion par défaut, appelez stop() ou renvoyez false.

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (InvalidOrderException $e) {
        // ...
    })->stop();
})

Le helper `report()`

Pour signaler une exception sans interrompre la réponse, utilisez le helper report().

public function isValid(string $value): bool
{
    try {
        // Validation...
    } catch (Throwable $e) {
        report($e);

        return false;
    }
}

Le helper report() permet de tracer une erreur sans interrompre la réponse à l’utilisateur. Il est particulièrement utile dans les jobs en arrière-plan ou pour des traitements non critiques.

Éviter les doublons de reporting

Si la même instance d’exception est passée plusieurs fois à report(), plusieurs entrées peuvent apparaître dans les logs. Configurez dontReportDuplicates() pour qu’une même instance ne soit journalisée que la première fois.

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReportDuplicates();
})

$original = new RuntimeException('Whoops!');

report($original); // journalisé

try {
    throw $original;
} catch (Throwable $caught) {
    report($caught); // ignoré (même instance)
}

Contexte global de log

Pour ajouter des informations communes à tous les logs d’exception, utilisez la méthode context. L’identifiant de l’utilisateur courant est automatiquement joint lorsqu’il est disponible.

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->context(fn () => [
        'app_version' => config('app.version'),
    ]);
})

Ajouter `context()` à une classe d’exception

En définissant une méthode context() sur une classe d’exception, vous joignez à ses logs des informations qui lui sont propres.

<?php

namespace App\Exceptions;

use Exception;

class InvalidOrderException extends Exception
{
    public function __construct(
        private readonly int $orderId,
        string $message = '',
    ) {
        parent::__construct($message);
    }

    /**
     * Renvoie le contexte associé à l'exception.
     *
     * @return array<string, mixed>
     */
    public function context(): array
    {
        return ['order_id' => $this->orderId];
    }
}

Modifier le niveau de log

Pour journaliser une exception donnée à un niveau spécifique, utilisez level.

use PDOException;
use Psr\Log\LogLevel;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->level(PDOException::class, LogLevel::CRITICAL);
})

Throttling du reporting

Si un très grand nombre d’exceptions se produit, la méthode throttle permet de limiter le volume de reporting.

use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    // N'en signaler qu'environ 1 sur 1000, de manière aléatoire
    $exceptions->throttle(function (Throwable $e) {
        return Lottery::odds(1, 1000);
    });
})

Pour limiter au nombre par minute, utilisez Limit.

use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->throttle(function (Throwable $e) {
        if ($e instanceof BroadcastException) {
            return Limit::perMinute(300);
        }
    });
})

Rendu des exceptions

Le rendu transforme une exception en réponse HTTP. Par défaut, Laravel produit une réponse appropriée ; vous pouvez néanmoins la personnaliser.

Callback de rendu personnalisé

Passez une closure à render pour convertir une exception en réponse.

use App\Exceptions\InvalidOrderException;
use Illuminate\Http\Request;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (InvalidOrderException $e, Request $request) {
        return response()->view('errors.invalid-order', status: 500);
    });
})

Vous pouvez aussi surcharger le rendu des exceptions natives (comme NotFoundHttpException). Si la closure ne retourne rien, le rendu par défaut est utilisé.

use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Record not found.',
            ], 404);
        }
        // Retourner null utilise la page 404 par défaut
    });
})

Détection automatique JSON / HTML

Laravel décide automatiquement de renvoyer du HTML ou du JSON en s’appuyant sur l’en-tête Accept de la requête. Pour personnaliser cette logique, utilisez shouldRenderJsonWhen.

use Illuminate\Http\Request;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
        if ($request->is('admin/*')) {
            return true; // L'administration renvoie toujours du JSON
        }

        return $request->expectsJson();
    });
})

Personnaliser la réponse finale

respond permet d’agir sur la réponse déjà générée.

use Symfony\Component\HttpFoundation\Response;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->respond(function (Response $response) {
        if ($response->getStatusCode() === 419) {
            return back()->with([
                'message' => 'La page a expiré, veuillez réessayer.',
            ]);
        }

        return $response;
    });
})

Classes d’exception personnalisées

Vous pouvez créer vos propres classes d’exception dans app/Exceptions/. En définissant les méthodes report() et render(), elles sont automatiquement appelées, sans configuration supplémentaire dans bootstrap/app.php.

Créer une classe d’exception

Générer la classe

php artisan make:exception InvalidOrderException

Implémenter report() et render()

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class InvalidOrderException extends Exception
{
    public function __construct(
        private readonly int $orderId,
        string $message = 'Invalid order.',
    ) {
        parent::__construct($message);
    }

    /**
     * Reporter l'exception.
     */
    public function report(): void
    {
        // Notification à un service externe, etc.
    }

    /**
     * Convertir l'exception en réponse HTTP.
     */
    public function render(Request $request): Response
    {
        return response()->view('errors.invalid-order', [
            'orderId' => $this->orderId,
        ], 422);
    }
}

Vous pouvez utiliser l’injection de dépendances via un type-hint dans report() : le service container de Laravel la résoudra automatiquement.

L’interface `ShouldntReport`

Pour les exceptions qui ne doivent pas être signalées, implémentez l’interface ShouldntReport. Une exception implémentant cette interface n’est jamais reportée.

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Contracts\Debug\ShouldntReport;

class PodcastProcessingException extends Exception implements ShouldntReport
{
    //
}

Lever des exceptions

Le helper `abort()`

Vous pouvez générer une réponse d’erreur HTTP depuis n’importe où dans l’application.

// 404 Not Found
abort(404);

// Avec un message
abort(403, 'Vous n\'avez pas les droits pour effectuer cette action.');

`abort_if()` / `abort_unless()`

Ce sont des helpers conditionnels pour lever une exception.

// Abort si la condition est vraie
abort_if(! $user->isAdmin(), 403);

// Abort si la condition est fausse
abort_unless($user->hasPermission('edit'), 403, 'Permission denied.');

Ils sont pratiques pour les vérifications de droits dans un contrôleur ou un middleware. On les combine souvent avec des gates ou des policies.

Contrôle global des exceptions

Ignorer certaines exceptions

Utilisez dontReport pour indiquer les exceptions à ne pas signaler. La logique de rendu personnalisée reste, elle, active.

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReport([
        InvalidOrderException::class,
    ]);
})

Pour ignorer sous condition, passez une closure à dontReportWhen.

use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReportWhen(function (Throwable $e) {
        return $e instanceof PodcastProcessingException &&
               $e->reason() === 'Subscription expired';
    });
})

Par défaut, Laravel ignore automatiquement certaines exceptions comme les erreurs 404, les erreurs de CSRF (419) ou les incohérences d’origine (403).

Réactiver le reporting d’exceptions ignorées

Pour rétablir le reporting d’exceptions ignorées par défaut, utilisez stopIgnoring.

use Symfony\Component\HttpKernel\Exception\HttpException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->stopIgnoring(HttpException::class);
})

Pages d’erreur HTTP

Laravel permet de définir une vue d’erreur personnalisée par code de statut HTTP.

Créer des vues d’erreur personnalisées

Créez, dans le répertoire resources/views/errors/, un template Blade dont le nom de fichier correspond au code de statut.

resources/
└── views/
    └── errors/
        ├── 404.blade.php
        ├── 403.blade.php
        └── 500.blade.php

Dans la vue, la variable $exception donne accès aux informations d’erreur.

{{-- resources/views/errors/404.blade.php --}}
<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <title>Page introuvable</title>
</head>
<body>
    <h1>404 — Page introuvable</h1>
    <p>{{ $exception->getMessage() }}</p>
    <a href="{{ url('/') }}">Retour à l'accueil</a>
</body>
</html>

Publier les templates d’erreur par défaut

Pour partir des pages d’erreur standard de Laravel, publiez-les via vendor:publish.

php artisan vendor:publish --tag=laravel-errors

Pages d’erreur de secours

Comme fallback pour les codes de statut qui n’ont pas de vue dédiée, créez 4xx.blade.php et 5xx.blade.php.

resources/
└── views/
    └── errors/
        ├── 4xx.blade.php  # Fallback pour les 4xx
        └── 5xx.blade.php  # Fallback pour les 5xx

Laravel fournit des pages d’erreur par défaut pour 404, 500 et 503. Pour les personnaliser, créez le fichier dédié (par ex. 404.blade.php) plutôt que de vous appuyer sur le fallback.

Exemple concret : handler d’exceptions pour API

Une application qui expose une API doit systématiquement renvoyer du JSON. Voici un exemple de centralisation des erreurs API dans bootstrap/app.php.

use Illuminate\Auth\AuthenticationException;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

->withExceptions(function (Exceptions $exceptions): void {
    // Les requêtes API renvoient toujours du JSON
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Ressource introuvable.',
            ], 404);
        }
    });

    $exceptions->render(function (AuthenticationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Authentification requise.',
            ], 401);
        }
    });

    $exceptions->render(function (ValidationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Erreur de validation.',
                'errors'  => $e->errors(),
            ], 422);
        }
    });
})

Implémenter une classe d’exception API dédiée

Une classe d’exception de base dédiée à l’API permet de garantir une réponse d’erreur homogène pour tous les endpoints.

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class ApiException extends Exception
{
    public function __construct(
        string $message = 'An error occurred.',
        private readonly int $statusCode = 500,
        private readonly array $errors = [],
    ) {
        parent::__construct($message);
    }

    public function render(Request $request): JsonResponse
    {
        $data = ['message' => $this->getMessage()];

        if (! empty($this->errors)) {
            $data['errors'] = $this->errors;
        }

        return response()->json($data, $this->statusCode);
    }
}

Exemple d’utilisation dans un contrôleur :

<?php

namespace App\Http\Controllers\Api;

use App\Exceptions\ApiException;
use App\Models\Order;

class OrderController extends Controller
{
    public function show(int $id): JsonResponse
    {
        $order = Order::find($id);

        if (! $order) {
            throw new ApiException('Commande introuvable.', 404);
        }

        if ($order->isCancelled()) {
            throw new ApiException('Cette commande a déjà été annulée.', 422);
        }

        return response()->json($order);
    }
}

Récapitulatif

Récapitulatif du reporting

Méthode	Rôle
`$exceptions->report()`	Enregistrer une logique de reporting spécifique à un type d’exception
`$exceptions->context()`	Ajouter un contexte commun à tous les logs d’exception
Méthode `context()`	Attacher un contexte propre à une classe d’exception
Helper `report()`	Signaler une exception sans interrompre la réponse
`dontReportDuplicates()`	Éviter les doublons pour une même instance
Interface `ShouldntReport`	Créer une exception qui ne doit jamais être signalée

Récapitulatif du rendu

Méthode	Rôle
`$exceptions->render()`	Retourner une réponse personnalisée selon le type d’exception
Méthode `render()`	Attacher la logique de rendu à la classe d’exception
`shouldRenderJsonWhen()`	Personnaliser la logique JSON/HTML
`respond()`	Modifier la réponse déjà générée

Récapitulatif des pages d'erreur HTTP

Créer un fichier comme resources/views/errors/404.blade.php suffit à l’activer.
La variable $exception donne accès au détail de l’erreur.
php artisan vendor:publish --tag=laravel-errors permet de récupérer les templates par défaut.
4xx.blade.php / 5xx.blade.php définissent des pages de secours.

Bonnes pratiques en production

Toujours fixer APP_DEBUG=false pour ne pas exposer la stack trace aux utilisateurs.
Intégrer un service de suivi d’erreurs comme Sentry ou Flare pour centraliser les incidents.
Utiliser throttle() pour éviter la saturation des logs en cas de pic d’exceptions.
Sur une API, conserver un format JSON d’erreur cohérent pour tous les endpoints.

​Aperçu

​Flux de traitement des exceptions

​Configuration du mode debug

​Signalement des exceptions

​Callbacks de reporting personnalisés

​Le helper report()

​Éviter les doublons de reporting

​Contexte global de log

​Ajouter context() à une classe d’exception

​Modifier le niveau de log

​Throttling du reporting

​Rendu des exceptions

​Callback de rendu personnalisé

​Détection automatique JSON / HTML

​Personnaliser la réponse finale

​Classes d’exception personnalisées

​Créer une classe d’exception

​L’interface ShouldntReport

​Lever des exceptions

​Le helper abort()

​abort_if() / abort_unless()

​Contrôle global des exceptions

​Ignorer certaines exceptions

​Réactiver le reporting d’exceptions ignorées

​Pages d’erreur HTTP

​Créer des vues d’erreur personnalisées

​Publier les templates d’erreur par défaut

​Pages d’erreur de secours

​Exemple concret : handler d’exceptions pour API

​Implémenter une classe d’exception API dédiée

​Récapitulatif

Aperçu

Flux de traitement des exceptions

Configuration du mode debug

Signalement des exceptions

Callbacks de reporting personnalisés

Le helper `report()`

Éviter les doublons de reporting

Contexte global de log

Ajouter `context()` à une classe d’exception

Modifier le niveau de log

Throttling du reporting

Rendu des exceptions

Callback de rendu personnalisé

Détection automatique JSON / HTML

Personnaliser la réponse finale

Classes d’exception personnalisées

Créer une classe d’exception

L’interface `ShouldntReport`

Lever des exceptions

Le helper `abort()`

`abort_if()` / `abort_unless()`

Contrôle global des exceptions

Ignorer certaines exceptions

Réactiver le reporting d’exceptions ignorées

Pages d’erreur HTTP

Créer des vues d’erreur personnalisées

Publier les templates d’erreur par défaut

Pages d’erreur de secours

Exemple concret : handler d’exceptions pour API

Implémenter une classe d’exception API dédiée

Récapitulatif