Foutafhandeling - Knowledge of Laravel

Overzicht

Wanneer je een Laravel-project aanmaakt, is de afhandeling van fouten en exceptions al voor je geconfigureerd. Aanpassen doe je met de withExceptions-methode in bootstrap/app.php.

De exception-afhandelingsflow

Zo verloopt de stroom van het optreden van een exception tot de response die naar de client wordt teruggestuurd.

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

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions): void {
        // Configureer hier het rapporteren en renderen van exceptions
    })->create();

Het $exceptions-object dat aan de withExceptions-closure wordt doorgegeven, is een instantie van Illuminate\Foundation\Configuration\Exceptions en beheert de exception-afhandeling van je hele applicatie.

Debugconfiguratie

De debug-optie in config/app.php bepaalt hoeveel foutinformatie wordt getoond. Standaard wordt de waarde van de omgevingsvariabele APP_DEBUG uit .env gebruikt.

# Lokale ontwikkeling
APP_DEBUG=true

# Productie
APP_DEBUG=false

Zet APP_DEBUG in productie altijd op false. Als je hem op true laat staan, loop je het risico dat vertrouwelijke informatie aan eindgebruikers wordt blootgesteld.

Exceptions rapporteren

Het rapporteren van exceptions houdt in dat je exceptions logt of doorstuurt naar externe services zoals Laravel Nightwatch, Sentry of Flare. Standaard worden ze gelogd op basis van de configuratie in config/logging.php.

Eigen rapportagecallbacks

Wil je per soort exception een andere rapportagelogica, geef dan een closure door aan de report-methode. Laravel bepaalt het soort exception op basis van de type-hint van de closure.

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (InvalidOrderException $e) {
        // Notificatie naar externe services, enz.
    });
})

Ook na het registreren van een eigen callback blijft de standaardlogging actief. Wil je de doorgifte naar de standaardafhandeling stoppen, roep dan stop() aan of geef false terug.

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

De `report()`-helper

Wil je alleen een exception rapporteren zonder een foutpagina te tonen, gebruik dan de report()-helper.

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

        return false;
    }
}

Met de report()-helper kun je een fout loggen zonder de response naar de gebruiker te onderbreken. Handig voor exception-afhandeling in achtergrondjobs en niet-kritieke processen.

Dubbele rapportages voorkomen

Als dezelfde exception-instantie meerdere keren aan report() wordt doorgegeven, kunnen er dubbele logregels ontstaan. Met dontReportDuplicates() wordt dezelfde instantie alleen de eerste keer gelogd.

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

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

report($original); // Wordt gelogd

try {
    throw $original;
} catch (Throwable $caught) {
    report($caught); // Wordt genegeerd (dezelfde instantie)
}

Globale logcontext

Wil je aan alle exceptionlogs gemeenschappelijke informatie toevoegen, gebruik dan de context-methode. Indien beschikbaar wordt het ID van de huidige gebruiker automatisch toegevoegd.

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

Een `context()`-methode toevoegen aan een exceptionklasse

Als je op de exceptionklasse zelf een context()-methode definieert, kun je contextinformatie specifiek voor die exception in de logs opnemen.

<?php

namespace App\Exceptions;

use Exception;

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

    /**
     * Geef de contextinformatie van de exception terug
     *
     * @return array<string, mixed>
     */
    public function context(): array
    {
        return ['order_id' => $this->orderId];
    }
}

Het logniveau wijzigen

Wil je een specifieke exception op een specifiek logniveau loggen, gebruik dan de level-methode.

use PDOException;
use Psr\Log\LogLevel;

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

Exception-rapportages throttlen

Als er grote aantallen exceptions optreden, kun je met de throttle-methode het aantal rapportages beperken.

use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    // Slechts 1 op de 1000 keer willekeurig rapporteren
    $exceptions->throttle(function (Throwable $e) {
        return Lottery::odds(1, 1000);
    });
})

Wil je begrenzen op het aantal per minuut, gebruik dan 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);
        }
    });
})

Exceptions renderen

Renderen is het omzetten van een exception naar een HTTP-response. Standaard genereert Laravel automatisch een passende response, maar je kunt dit aanpassen.

Eigen rendercallbacks

Geef een closure door aan de render-methode om een exception naar een response om te zetten.

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);
    });
})

Je kunt ook het renderen van ingebouwde exceptions (zoals NotFoundHttpException) overschrijven. Als de closure geen waarde teruggeeft, wordt de standaardrendering gebruikt.

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);
        }
        // Als je null teruggeeft, wordt de standaard 404-pagina getoond
    });
})

Automatische JSON/HTML-detectie

Laravel bepaalt automatisch of het HTML of JSON teruggeeft op basis van de Accept-header van het request. Wil je deze beslislogica aanpassen, gebruik dan 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; // Het beheerderspaneel krijgt altijd JSON terug
        }

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

De volledige response aanpassen

Met de respond-methode kun je de gegenereerde response verder bewerken.

use Symfony\Component\HttpFoundation\Response;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->respond(function (Response $response) {
        if ($response->getStatusCode() === 419) {
            return back()->with([
                'message' => 'De pagina is verlopen. Probeer het opnieuw.',
            ]);
        }

        return $response;
    });
})

Eigen exceptionklassen

Je kunt eigen exceptionklassen maken in de map app/Exceptions/. Als je de methoden report() en render() definieert, worden ze automatisch aangeroepen zonder dat je configuratie in bootstrap/app.php hoeft te schrijven.

Een exceptionklasse maken

Maak de exceptionklasse aan

php artisan make:exception InvalidOrderException

Implementeer report() en 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);
    }

    /**
     * Rapporteer de exception
     */
    public function report(): void
    {
        // Notificatie naar externe services, enz.
    }

    /**
     * Zet de exception om naar een HTTP-response
     */
    public function render(Request $request): Response
    {
        return response()->view('errors.invalid-order', [
            'orderId' => $this->orderId,
        ], 422);
    }
}

In de report()-methode kun je dependency injection via type-hints gebruiken. De servicecontainer van Laravel lost ze automatisch op.

De `ShouldntReport`-interface

Voor exceptions die geen rapportage nodig hebben, implementeer je de ShouldntReport-interface. Exceptions die deze interface implementeren, worden nooit gerapporteerd.

<?php

namespace App\Exceptions;

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

class PodcastProcessingException extends Exception implements ShouldntReport
{
    //
}

Exceptions gooien

De `abort()`-helper

Vanaf elke plek in je applicatie kun je een HTTP-foutresponse laten optreden.

// 404 Not Found
abort(404);

// Met bericht
abort(403, 'Je bent niet gemachtigd om deze actie uit te voeren.');

`abort_if()` / `abort_unless()`

Helpers om voorwaardelijk een exception te gooien.

// Abort wanneer $condition true is
abort_if(! $user->isAdmin(), 403);

// Abort wanneer $condition false is
abort_unless($user->hasPermission('edit'), 403, 'Permission denied.');

Handig bij permissiecontroles in controllers en middleware. Wordt ook vaak gebruikt in combinatie met gates en policies.

Exceptions globaal beheren

Specifieke exceptions negeren

Met dontReport geef je exceptions op die niet gerapporteerd worden. Eigen renderlogica blijft wel gewoon werken.

use App\Exceptions\InvalidOrderException;

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

Wil je voorwaardelijk negeren, geef dan een closure door aan dontReportWhen.

use Throwable;

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

Laravel negeert standaard automatisch een aantal exceptions, zoals 404-fouten, ongeldige CSRF-tokens (419) en niet-overeenkomende origins (403).

Door Laravel genegeerde exceptions weer inschakelen

Om exceptions die standaard worden genegeerd weer te laten rapporteren, gebruik je stopIgnoring.

use Symfony\Component\HttpKernel\Exception\HttpException;

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

HTTP-foutpagina’s

In Laravel kun je per HTTP-statuscode eigen foutviews definiëren.

Eigen foutviews maken

Maak in de map resources/views/errors/ Blade-templates aan met de statuscode als bestandsnaam.

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

Binnen de view heb je via de variabele $exception toegang tot de foutinformatie.

{{-- resources/views/errors/404.blade.php --}}
<!DOCTYPE html>
<html lang="nl">
<head>
    <meta charset="UTF-8">
    <title>Pagina niet gevonden</title>
</head>
<body>
    <h1>404 - Pagina niet gevonden</h1>
    <p>{{ $exception->getMessage() }}</p>
    <a href="{{ url('/') }}">Terug naar de startpagina</a>
</body>
</html>

De standaardfouttemplates publiceren

Wil je de standaardfoutpagina’s van Laravel als startpunt voor aanpassing gebruiken, haal ze dan op met vendor:publish.

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

Fallback-foutpagina’s

Als fallback voor statuscodes zonder bijbehorende view kun je 4xx.blade.php en 5xx.blade.php aanmaken.

resources/
└── views/
    └── errors/
        ├── 4xx.blade.php  # Fallback voor de 400-reeks
        └── 5xx.blade.php  # Fallback voor de 500-reeks

Voor 404, 500 en 503 heeft Laravel standaardfoutpagina’s. Om deze aan te passen, maak je aparte bestanden (zoals 404.blade.php) in plaats van fallbacks.

Praktijkvoorbeeld: een API-exceptionhandler

In applicaties die een API aanbieden, moeten exceptions altijd als JSON worden teruggegeven. Hieronder een implementatievoorbeeld waarbij API-fouten centraal worden beheerd in 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 {
    // API-requests krijgen altijd JSON terug
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Resource niet gevonden.',
            ], 404);
        }
    });

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

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

Een eigen API-exceptionklasse implementeren

Met een basisexceptionklasse speciaal voor je API kun je op elk endpoint een uniforme foutresponse teruggeven.

<?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);
    }
}

Een gebruiksvoorbeeld in een controller:

<?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('Bestelling niet gevonden.', 404);
        }

        if ($order->isCancelled()) {
            throw new ApiException('Deze bestelling is al geannuleerd.', 422);
        }

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

Samenvatting

Samenvatting van exception-rapportage

Methode	Gebruik
`$exceptions->report()`	Eigen rapportagelogica per soort exception registreren
`$exceptions->context()`	Gemeenschappelijke informatie toevoegen aan alle exceptionlogs
De `context()`-methode	Contextinformatie op de exceptionklasse zelf
De `report()`-helper	Alleen de exception rapporteren zonder de response te onderbreken
`dontReportDuplicates()`	Dubbele rapportages van dezelfde instantie voorkomen
De `ShouldntReport`-interface	Exceptionklassen maken die nooit worden gerapporteerd

Samenvatting van exception-rendering

Methode	Gebruik
`$exceptions->render()`	Eigen responses teruggeven per soort exception
De `render()`-methode	Renderlogica op de exceptionklasse zelf
`shouldRenderJsonWhen()`	De JSON/HTML-beslislogica aanpassen
`respond()`	De gegenereerde response verder bewerken

Samenvatting van HTTP-foutpagina's

Bestanden zoals resources/views/errors/404.blade.php worden automatisch gebruikt zodra je ze aanmaakt
Via de variabele $exception heb je toegang tot de foutdetails
Met php artisan vendor:publish --tag=laravel-errors haal je de standaardtemplates op
Met 4xx.blade.php / 5xx.blade.php definieer je fallback-pagina’s

Best practices voor productie

Zet altijd APP_DEBUG=false en toon stacktraces niet aan gebruikers
Koppel externe fouttrackingservices zoals Sentry of Flare om fouten centraal te beheren
Gebruik throttle() om logoverstroming te voorkomen bij grote aantallen exceptions
Handhaaf een consistent JSON-foutresponseformaat op API-endpoints

​Overzicht

​De exception-afhandelingsflow

​Debugconfiguratie

​Exceptions rapporteren

​Eigen rapportagecallbacks

​De report()-helper

​Dubbele rapportages voorkomen

​Globale logcontext

​Een context()-methode toevoegen aan een exceptionklasse

​Het logniveau wijzigen

​Exception-rapportages throttlen

​Exceptions renderen

​Eigen rendercallbacks

​Automatische JSON/HTML-detectie

​De volledige response aanpassen

​Eigen exceptionklassen

​Een exceptionklasse maken

​De ShouldntReport-interface

​Exceptions gooien

​De abort()-helper

​abort_if() / abort_unless()

​Exceptions globaal beheren

​Specifieke exceptions negeren

​Door Laravel genegeerde exceptions weer inschakelen

​HTTP-foutpagina’s

​Eigen foutviews maken

​De standaardfouttemplates publiceren

​Fallback-foutpagina’s

​Praktijkvoorbeeld: een API-exceptionhandler

​Een eigen API-exceptionklasse implementeren

​Samenvatting

Overzicht

De exception-afhandelingsflow

Debugconfiguratie

Exceptions rapporteren

Eigen rapportagecallbacks

De `report()`-helper

Dubbele rapportages voorkomen

Globale logcontext

Een `context()`-methode toevoegen aan een exceptionklasse

Het logniveau wijzigen

Exception-rapportages throttlen

Exceptions renderen

Eigen rendercallbacks

Automatische JSON/HTML-detectie

De volledige response aanpassen

Eigen exceptionklassen

Een exceptionklasse maken

De `ShouldntReport`-interface

Exceptions gooien

De `abort()`-helper

`abort_if()` / `abort_unless()`

Exceptions globaal beheren

Specifieke exceptions negeren

Door Laravel genegeerde exceptions weer inschakelen

HTTP-foutpagina’s

Eigen foutviews maken

De standaardfouttemplates publiceren

Fallback-foutpagina’s

Praktijkvoorbeeld: een API-exceptionhandler

Een eigen API-exceptionklasse implementeren

Samenvatting