README

This Laravel package lets you define the behavior of your application when a specific exception is thrown.

Laravel handles exceptions in app/Exceptions/Handler.php by default, but the more handlers you add the more this class gets cluttered and difficult to read and maintain.

Furthermore it is not possible for an external Laravel package to automatically register how its custom exceptions should be handled by the application where it has been installed.

This package lets you register custom exception handlers by using service providers, so that also external packages may register their own.

Please note: this package leverages the decorators design pattern, which allows you to keep using the Laravel default handler as you normally would. It just wraps the exception handler to extend its functionalities.

Install

Via Composer

composer require cerbero/exception-handler

If your Laravel version is prior to 5.5, please add this service provider in config/app.php

'providers' => [
    ...
    Cerbero\ExceptionHandler\Providers\ExceptionHandlerServiceProvider::class,
]

Usage

There are 3 types of handlers that can be registered:

Reporters, they log an exception or report it to an external service (e.g. Sentry, Bugsnag...)
Renderers, they render an exception into an HTTP response
Console Renderers, they render an exception to the console

The following examples show how to register each type of handler in the boot() method of a service provider:

use App\Exceptions\DebugException;
use App\Exceptions\ArtisanException;
use Illuminate\Contracts\Debug\ExceptionHandler;
use Illuminate\Contracts\Validation\ValidationException;

...

public function boot()
{
    // register a custom reporter to log all exceptions that are instances of - or extend - DebugException
    $this->app->make(ExceptionHandler::class)->reporter(function (DebugException $e) {
        $this->app['log']->debug($e->getMessage());
    });

    // register a custom renderer to redirect the user back and show validation errors
    $this->app->make(ExceptionHandler::class)->renderer(function (ValidationException $e, $request) {
        return back()->withInput()->withErrors($e->errors());
    });

    // register a custom console renderer to display errors to the console and stop the propagation of other exceptions
    $this->app->make(ExceptionHandler::class)->consoleRenderer(function (ArtisanException $e, $output) {
        $output->writeln('<error>' . $e->getMessage() . '</error>');
        return true;
    });
}

A handler is basically a callback that accepts the exception to handle as first parameter. You can register a global handler by omitting the exception type or type-hinting Exception.

Unlike reporters, renderers also accept a second parameter: an instance of Illuminate\Http\Request in case of a renderer or a Symfony\Component\Console\Output\OutputInterface in case of a console renderer.

It is also important to note that all registered handlers for an exception will be called until one of them returns a truthy value, in that case the exceptions propagation stops.

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email andrea.marco.sartori@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

cerbero / exception-handler

Maintainers

Details