Gestione delle eccezioni in Laravel

Italian (Italiano) translation by Francesco (you can also view the original English article)

In questo articolo esploreremo una delle funzionalità più importanti e meno dscusse del framework web laravel - la gestione delle eccezioni. Laravel è distribuito con un gestore di eccezioni integrato che ti permette di riportare e visualizzare le eccezioni in modo semplice e veloce.

Nella prima metà dell'articolo esploreremo le impostazioni di default fornite dal gestore di eccezioni. Infatti analizzeremo la classe di default per capire come Laravel gestisce le eccezioni.

Nella seconda metà dell'articolo, vedremo come creare un gestore di eccezioni che ci permetta di catturare le eccezioni personalizzate.

Impostazioni preliminari

Prima di andare avanti e analizzare la classe Handler, diamo uno sguardo ad un paio di parametri di configurazione importanti relativi alle eccezioni.

Apriamo il file config/app.php. Diamo un'occhiata al seguente snippet.

...
...
/*
|--------------------------------------------------------------------------
| Application Debug Mode
|--------------------------------------------------------------------------
|
| When your application is in debug mode, detailed error messages with
| stack traces will be shown on every error that occurs within your
| application. If disabled, a simple generic error page is shown.
|
*/

'debug' => env('APP_DEBUG', false),
...
...

Come suggerisce il nome, se impostato su TRUE, ti aiuterà a gestire il debug degli errori generati dall'applicazione. Il valore di default di questa variabile è impostato nel valore APP_DEBUG nel file .env.

Nell'ambiente di sviluppo dovresti impostarla su TRUE in modo da tracciare facilmente gli errori e risolverli. Invece, se sei in ambiente di produzione è meglio disattivarla e visualizzare un errore generico.

Oltre che mostrare gli errori, Laravel permette di loggare gli errori in un file di log. Diamo una rapida occhiata alle opzioni disponibili. Torniamo al file config/app.php e guardiamo il seguente snippet.

...
...
'log' => env('APP_LOG', 'single'),

'log_level' => env('APP_LOG_LEVEL', 'debug'),
...
...

Poichè Laravel usa la libreria Monolog per il logging, dovrai impostare le seguenti opzioni.

Il file di log di default si trova in storage/logs/laravel.log, ed è sufficiente per la maggior parte dei casi. Inoltre la variabile APP_LOG_LEVEL è impostata su un valore che indica la severità degli errori da loggare.

Questa è una rapida introduzione alle opzioni di configurazione disponibili per le eccezioni e il logging.

Vediamo ora la class di default integrata nell'applicazione Laravel. Apriamo il file app/Exceptions/Handler.php.

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;

class Handler extends ExceptionHandler
{
    /**
     * A list of the exception types that should not be reported.
     *
     * @var array
     */
    protected $dontReport = [
        \Illuminate\Auth\AuthenticationException::class,
        \Illuminate\Auth\Access\AuthorizationException::class,
        \Symfony\Component\HttpKernel\Exception\HttpException::class,
        \Illuminate\Database\Eloquent\ModelNotFoundException::class,
        \Illuminate\Session\TokenMismatchException::class,
        \Illuminate\Validation\ValidationException::class,
    ];

    /**
     * Report or log an exception.
     *
     * This is a great spot to send exceptions to Sentry, Bugsnag, etc.
     *
     * @param  \Exception  $exception
     * @return void
     */
    public function report(Exception $exception)
    {
        parent::report($exception);
    }

    /**
     * Render an exception into an HTTP response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Exception  $exception
     * @return \Illuminate\Http\Response
     */
    public function render($request, Exception $exception)
    {
        return parent::render($request, $exception);
    }

    /**
     * Convert an authentication exception into an unauthenticated response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Illuminate\Auth\AuthenticationException  $exception
     * @return \Illuminate\Http\Response
     */
    protected function unauthenticated($request, AuthenticationException $exception)
    {
        if ($request->expectsJson()) {
            return response()->json(['error' => 'Unauthenticated.'], 401);
        }

        return redirect()->guest(route('login'));
    }
}

Ci sono due funzioni importanti di cui è responsabile la classe - gestire e visualizzare tutti gli errori.

Diamo un'occhiata al metodo report.

/**
 * Report or log an exception.
 *
 * This is a great spot to send exceptions to Sentry, Bugsnag, etc.
 *
 * @param  \Exception  $exception
 * @return void
 */
public function report(Exception $exception)
{
    parent::report($exception);
}

Il metodo report è usato per loggare gli errori nel file di log. Allo stesso tempo è importante notare la proprietà dontReport, che elenca tutti i tipi di errori che non devono essere loggati.

Vediamo il metodo render.

/**
 * Render an exception into an HTTP response.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Exception  $exception
 * @return \Illuminate\Http\Response
 */
public function render($request, Exception $exception)
{
    return parent::render($request, $exception);
}

Se il metodo report è usato per loggare gli errori, il metodo render è usato per mostrali sullo schermo. Infatti questo metodo gestisce cosa deve essere mostrato all'utente quando viene laciata un'eccezione.

Il metodo render permette anche di personalizzare la risposta di errore in base ai differenti tipi di eccezioni, come vedremo nella prossima sezione.

Infine, il metodo unauthenticated gestisce le eccezioni AuthenticationException che ti permettono di decidere cosa mostrare agli utenti nel caso non siano autorizzati ad accedere alla pagina.

Custom exception Class

In questa sezione creeremo una classe personalizzata di gestione delle eccezioni di tipo CustomException. L'idea dietro alla creazione di classi di eccezione personalizzate è di gestire in modo facile le eccezioni personalizzate e mostrarle all'utente.

Creiamo il file app/Exceptions/CustomException.php con il seguente contenuto.

<?php

namespace App\Exceptions;

use Exception;

class CustomException extends Exception
{
    /**
     * Report the exception.
     *
     * @return void
     */
    public function report()
    {
    }

    /**
     * Render the exception into an HTTP response.
     *
     * @param  \Illuminate\Http\Request
     * @return \Illuminate\Http\Response
     */
    public function render($request)
    {
        return response()->view(
                'errors.custom',
                array(
                    'exception' => $this
                )
        );
    }
}

La cosa importante da notare è che la classe CustomException deve estendere la classe Exception. Per dimostrarlo discuteremo solo del metodo render, ma ovviamente si può personalizzare ogni altro metodo.

Come puoi vedere, stiamo redirigendo gli utenti alla pagina errors.custom in questo caso. In questo modo puoi implementare pagine di errore per uno specifico errore.

Naturalmente, abbiamo bisogno di creare un file di visualizzazione associato a resources/views/errors/custom.blade.php.

Exception details: <b>{{ $exception->getMessage() }}</b>

Questo è un file di vista piuttosto semplice che visualizza un messaggio di errore, ma naturalmente si potrebbe progettare nel modo desiderato.

Dobbiamo anche effettuare dei cambiamenti nel metodo render del file app/Exceptions/Handler.php in modo che la nostra classe possa essere invocata. Sostituiamo il metodo render con il seguente contenuto nel file app/Exceptions/Handler.php.

...
...
/**
 * Render an exception into an HTTP response.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Exception  $exception
 * @return \Illuminate\Http\Response
 */
public function render($request, Exception $exception)
{
    if ($exception instanceof \App\Exceptions\CustomException)  {
        return $exception->render($request);
    }

    return parent::render($request, $exception);
}
...
...

Come potete vedere, stiamo verificando in primo luogo il tipo di eccezione nel metodo render. Se il tipo di eccezione è \App\Exceptions\CustomException, chiamiamo il metodo render della classe.

Così tutto è a posto ora. Andiamo avanti a creare un file di controller in app/Http/Controllers/ExceptionController.php così possiamo testare la nostra classe di eccezione personalizzata.

<?php
namespace App\Http\Controllers;

use App\Http\Controllers\Controller;

class ExceptionController extends Controller
{
    public function index()
    {
        // something went wrong and you want to throw CustomException
        throw new \App\Exceptions\CustomException('Something Went Wrong.');
    }
}

Naturalmente, è necessario aggiungere una route associata alla routes/web.php, come illustrato nel seguente frammento di codice.

// Exception routes
Route::get('exception/index', 'ExceptionController@index');

E con questo a disposizione, è possibile eseguire l'URL http://your-laravel-site.com/exception/index per vedere se funziona come previsto. Si dovrebbe visualizzare la vista errors.custom in base alla nostra configurazione.

Ecco come si dovrebbero gestire le eccezioni personalizzate in Laravel. E questo ci porta alla fine di questo articolo — spero che sia piaciuto!

Conclusione

Oggi abbiamo visto le funzionalità di gestione eccezioni in Laravel. All'inizio dell'articolo, abbiamo esplorato la configurazione di base fornita da Laravel al fine di eseguire il rendering e segnalare le eccezioni. Inoltre, abbiamo dato un breve sguardo alla classe del gestore eccezioni predefinito.

Nella seconda metà dell'articolo, abbiamo preparato una classe del gestore di eccezione personalizzata che ha dimostrato come si potrebbero gestire eccezioni personalizzate nell'applicazione.

Per quelli di voi che hanno da poco iniziato con Laravel o stanno cercando di espanderne la conoscenza, sito o applicazione con estensioni, abbiamo una varietà di cose che da studiare nel market di Envato.

Mi piacerebbe conoscere le vostre domande e i vostri suggerimenti!