Gestione degli errori - Knowledge of Laravel

Panoramica

Quando crei un progetto Laravel, la gestione di errori ed eccezioni è già configurata. Le personalizzazioni si effettuano nel metodo withExceptions di bootstrap/app.php.

Flusso di gestione delle eccezioni

Ecco il percorso dal momento in cui si verifica un’eccezione fino alla risposta al client.

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

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions): void {
        // configura qui report e rendering delle eccezioni
    })->create();

L’oggetto $exceptions passato alla closure di withExceptions è un’istanza di Illuminate\Foundation\Configuration\Exceptions e gestisce l’exception handling dell’intera applicazione.

Configurazione del debug

L’opzione debug in config/app.php controlla il livello di dettaglio delle informazioni di errore mostrate. Di default viene usato il valore della variabile d’ambiente APP_DEBUG nel .env.

# sviluppo locale
APP_DEBUG=true

# produzione
APP_DEBUG=false

In produzione imposta sempre APP_DEBUG a false. Lasciarlo a true rischia di esporre informazioni sensibili agli utenti finali.

Report delle eccezioni

“Fare il report” di un’eccezione significa registrarla nei log o inviarla a servizi esterni come Laravel Nightwatch, Sentry o Flare. Per default viene registrata nei log seguendo la configurazione di config/logging.php.

Callback di report personalizzata

Se vuoi trattare in modo diverso il report a seconda del tipo di eccezione, passa una closure al metodo report. Laravel determina il tipo di eccezione dall’hint di tipo della closure.

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (InvalidOrderException $e) {
        // notifica a un servizio esterno ecc.
    });
})

Anche registrando una callback personalizzata, la registrazione nei log di default continua. Per interrompere la propagazione al default, chiama stop() o restituisci false.

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

Helper `report()`

Se vuoi solo segnalare un’eccezione senza mostrare la pagina di errore, usa l’helper report().

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

        return false;
    }
}

L’helper report() permette di registrare l’errore senza interrompere la risposta all’utente. Ottimo per la gestione delle eccezioni in job in background o operazioni non critiche.

Prevenzione dei report duplicati

Se la stessa istanza di eccezione viene passata più volte a report(), si possono creare voci duplicate nei log. Impostando dontReportDuplicates(), la stessa istanza viene registrata solo la prima volta.

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

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

report($original); // registrata

try {
    throw $original;
} catch (Throwable $caught) {
    report($caught); // ignorata (stessa istanza)
}

Context globale del log

Per aggiungere informazioni comuni a tutti i log di eccezione usa il metodo context. Se disponibile, l’ID dell’utente corrente viene aggiunto automaticamente.

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

Aggiungere il metodo `context()` a una classe eccezione

Definendo il metodo context() sulla classe stessa dell’eccezione, puoi includere nel log informazioni di contesto specifiche di quella eccezione.

<?php

namespace App\Exceptions;

use Exception;

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

    /**
     * Restituisce le informazioni di contesto dell'eccezione
     *
     * @return array<string, mixed>
     */
    public function context(): array
    {
        return ['order_id' => $this->orderId];
    }
}

Modificare il log level

Per registrare una specifica eccezione con un particolare log level usa il metodo level.

use PDOException;
use Psr\Log\LogLevel;

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

Throttling dei report

Quando si verificano molte eccezioni, con il metodo throttle puoi controllare quante segnalare.

use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    // segnala in modo casuale una volta ogni 1000
    $exceptions->throttle(function (Throwable $e) {
        return Lottery::odds(1, 1000);
    });
})

Per limitare al minuto usa 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);
        }
    });
})

Rendering delle eccezioni

Il rendering è il processo che converte un’eccezione in una risposta HTTP. Per default Laravel genera automaticamente una risposta appropriata, ma puoi personalizzarla.

Callback di rendering personalizzata

Passa una closure al metodo render per convertire l’eccezione in una risposta.

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

Puoi sovrascrivere anche il rendering delle eccezioni built-in (come NotFoundHttpException). Se la closure non ritorna un valore, viene usato il rendering di default.

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);
        }
        // restituendo null viene mostrata la pagina 404 di default
    });
})

Rilevamento automatico JSON / HTML

Laravel decide automaticamente se restituire HTML o JSON in base all’header Accept della richiesta. Per personalizzare la logica di decisione usa 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; // area admin sempre in JSON
        }

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

Personalizzare l’intera risposta

Con il metodo respond puoi elaborare ulteriormente la risposta generata.

use Symfony\Component\HttpFoundation\Response;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->respond(function (Response $response) {
        if ($response->getStatusCode() === 419) {
            return back()->with([
                'message' => 'La pagina è scaduta. Riprova.',
            ]);
        }

        return $response;
    });
})

Classi di eccezione personalizzate

Puoi creare classi di eccezione personalizzate nella directory app/Exceptions/. Se definisci i metodi report() e render(), vengono richiamati automaticamente senza dover configurare bootstrap/app.php.

Creazione della classe di eccezione

Crea la classe di eccezione

php artisan make:exception InvalidOrderException

Implementa report() e 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);
    }

    /**
     * Report dell'eccezione
     */
    public function report(): void
    {
        // notifica a un servizio esterno ecc.
    }

    /**
     * Converte l'eccezione in risposta HTTP
     */
    public function render(Request $request): Response
    {
        return response()->view('errors.invalid-order', [
            'orderId' => $this->orderId,
        ], 422);
    }
}

Nel metodo report() puoi usare la dependency injection tramite hint di tipo. Il service container di Laravel la risolve automaticamente.

Interfaccia `ShouldntReport`

Per le eccezioni che non devi mai segnalare, implementa l’interfaccia ShouldntReport. Le eccezioni che la implementano non vengono mai riportate.

<?php

namespace App\Exceptions;

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

class PodcastProcessingException extends Exception implements ShouldntReport
{
    //
}

Sollevare eccezioni

Helper `abort()`

Da qualsiasi punto dell’applicazione puoi generare una risposta di errore HTTP.

// 404 Not Found
abort(404);

// con messaggio
abort(403, 'Non hai il permesso di eseguire questa operazione.');

`abort_if()` / `abort_unless()`

Helper per sollevare condizionalmente l’eccezione.

// abort se la condizione è true
abort_if(! $user->isAdmin(), 403);

// abort se la condizione è false
abort_unless($user->hasPermission('edit'), 403, 'Permission denied.');

Utile per controlli di autorizzazione in controller e middleware. Spesso si combina con gate e policy.

Controllo globale delle eccezioni

Ignorare eccezioni specifiche

Le eccezioni da non segnalare si indicano con dontReport. La logica di rendering personalizzata continua a funzionare.

use App\Exceptions\InvalidOrderException;

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

Per ignorare in base a una condizione passa una closure a dontReportWhen.

use Throwable;

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

Per default Laravel ignora automaticamente alcune eccezioni: errori 404, token CSRF non valido (419), origine non corrispondente (403) ecc.

Rimettere in report le eccezioni ignorate da Laravel

Per far tornare a essere riportate le eccezioni ignorate di default usa stopIgnoring.

use Symfony\Component\HttpKernel\Exception\HttpException;

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

Pagine di errore HTTP

In Laravel puoi definire view di errore personalizzate per singolo status HTTP.

Creare view di errore personalizzate

In resources/views/errors/ crea template Blade con lo status code come nome file.

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

Nella view accedi ai dettagli dell’errore tramite la variabile $exception.

{{-- resources/views/errors/404.blade.php --}}
<!DOCTYPE html>
<html lang="it">
<head>
    <meta charset="UTF-8">
    <title>Pagina non trovata</title>
</head>
<body>
    <h1>404 - Pagina non trovata</h1>
    <p>{{ $exception->getMessage() }}</p>
    <a href="{{ url('/') }}">Torna alla home</a>
</body>
</html>

Pubblicare i template di errore di default

Se vuoi partire dai template di errore di Laravel per personalizzarli, ottienili con vendor:publish.

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

Pagine di errore di fallback

Come fallback per gli status senza una view dedicata, puoi creare 4xx.blade.php e 5xx.blade.php.

resources/
└── views/
    └── errors/
        ├── 4xx.blade.php  # fallback per 4xx
        └── 5xx.blade.php  # fallback per 5xx

Per 404, 500 e 503 Laravel fornisce pagine di errore di default. Per personalizzarle crea i file dedicati (404.blade.php ecc.), non il fallback.

Esempio pratico: handler di eccezioni per API

Nelle applicazioni che espongono API, le eccezioni vanno sempre restituite come JSON. Ecco un esempio di gestione centralizzata degli errori API 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 {
    // le richieste API tornano sempre JSON
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Risorsa non trovata.',
            ], 404);
        }
    });

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

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

Implementare una classe base per le eccezioni API

Creando una classe base per le eccezioni di API puoi restituire risposte di errore uniformi da tutti gli endpoint.

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

Uso in un 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('Ordine non trovato.', 404);
        }

        if ($order->isCancelled()) {
            throw new ApiException('Questo ordine è già stato annullato.', 422);
        }

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

Riepilogo

Riepilogo del report delle eccezioni

Metodo	Uso
`$exceptions->report()`	Registra logica di report personalizzata per tipo di eccezione
`$exceptions->context()`	Aggiunge informazioni comuni a tutti i log delle eccezioni
Metodo `context()`	Dota la classe di eccezione di un contesto specifico
Helper `report()`	Segnala l’eccezione senza interrompere la risposta
`dontReportDuplicates()`	Evita report duplicati della stessa istanza
Interfaccia `ShouldntReport`	Crea eccezioni che non vengono mai riportate

Riepilogo del rendering delle eccezioni

Metodo	Uso
`$exceptions->render()`	Restituisce risposte personalizzate in base al tipo di eccezione
Metodo `render()`	Dota la classe di eccezione di logica di rendering
`shouldRenderJsonWhen()`	Personalizza la logica JSON/HTML
`respond()`	Elabora ulteriormente la risposta generata

Riepilogo delle pagine di errore HTTP

Bastano file come resources/views/errors/404.blade.php e vengono usati automaticamente
Con la variabile $exception accedi al dettaglio dell’errore
Con php artisan vendor:publish --tag=laravel-errors ottieni i template di default
4xx.blade.php / 5xx.blade.php definiscono pagine di fallback

Best practice in produzione

Imposta sempre APP_DEBUG=false per non mostrare la stack trace agli utenti
Integra servizi di error tracking come Sentry o Flare per centralizzare la gestione
Usa throttle() per evitare il flood dei log quando le eccezioni sono numerose
Negli endpoint API mantieni un formato di risposta di errore JSON coerente

​Panoramica

​Flusso di gestione delle eccezioni

​Configurazione del debug

​Report delle eccezioni

​Callback di report personalizzata

​Helper report()

​Prevenzione dei report duplicati

​Context globale del log

​Aggiungere il metodo context() a una classe eccezione

​Modificare il log level

​Throttling dei report

​Rendering delle eccezioni

​Callback di rendering personalizzata

​Rilevamento automatico JSON / HTML

​Personalizzare l’intera risposta

​Classi di eccezione personalizzate

​Creazione della classe di eccezione

​Interfaccia ShouldntReport

​Sollevare eccezioni

​Helper abort()

​abort_if() / abort_unless()

​Controllo globale delle eccezioni

​Ignorare eccezioni specifiche

​Rimettere in report le eccezioni ignorate da Laravel

​Pagine di errore HTTP

​Creare view di errore personalizzate

​Pubblicare i template di errore di default

​Pagine di errore di fallback

​Esempio pratico: handler di eccezioni per API

​Implementare una classe base per le eccezioni API

​Riepilogo

Panoramica

Flusso di gestione delle eccezioni

Configurazione del debug

Report delle eccezioni

Callback di report personalizzata

Helper `report()`

Prevenzione dei report duplicati

Context globale del log

Aggiungere il metodo `context()` a una classe eccezione

Modificare il log level

Throttling dei report

Rendering delle eccezioni

Callback di rendering personalizzata

Rilevamento automatico JSON / HTML

Personalizzare l’intera risposta

Classi di eccezione personalizzate

Creazione della classe di eccezione

Interfaccia `ShouldntReport`

Sollevare eccezioni

Helper `abort()`

`abort_if()` / `abort_unless()`

Controllo globale delle eccezioni

Ignorare eccezioni specifiche

Rimettere in report le eccezioni ignorate da Laravel

Pagine di errore HTTP

Creare view di errore personalizzate

Pubblicare i template di errore di default

Pagine di errore di fallback

Esempio pratico: handler di eccezioni per API

Implementare una classe base per le eccezioni API

Riepilogo