Master Laravel Exception Handling: From Configuration to Custom HTTP Errors

Exception Handling Overview

When you start a new Laravel project, the framework sets up error and exception handling through the app\exceptions\Handler class, which logs all exceptions and renders them for the user.

Configuration

The debug option in config/app.php determines how much error information is shown, based on the APP_DEBUG value in the .env file. For local development set APP_DEBUG=true; in production it should always be false to avoid exposing sensitive data.

Report Method

All exceptions are processed by App\Exceptions\Handler, which contains report and render methods. The report method logs the exception or forwards it to external services such as Bugsnag or Sentry. You can customize it, for example by checking the exception type with the instanceof operator:

/**
 * Report or log an exception.
 *
 * This is a good place to send the exception to external services.
 *
 * @param  \Exception  $exception
 * @return void
 */
public function report(Exception $exception)
{
    if ($exception instanceof CustomException) {
        // custom handling
    }
    parent::report($exception);
}

Tip: Avoid excessive instanceof checks in report ; consider using a reportable exception.

Global Context

Laravel automatically adds the current user ID to each log entry. You can override the context method in the handler to add custom global variables:

/**
 * Define default context variables.
 *
 * @return array
 */
protected function context()
{
    return array_merge(parent::context(), [
        'foo' => 'bar',
    ]);
}

Report Helper Function

The report helper allows you to quickly report an exception without halting the current request:

public function isValid($value)
{
    try {
        // validate value...
    } catch (Exception $e) {
        report($e);
        return false;
    }
}

Ignoring Exceptions by Type

The $dontReport property lists exception classes that should not be logged, such as authentication or 404 errors. Add additional types as needed:

protected $dontReport = [
    \Illuminate\Auth\AuthenticationException::class,
    \Illuminate\Auth\Access\AuthorizationException::class,
    \Symfony\Component\HttpKernel\Exception\HttpException::class,
    \Illuminate\Database\Eloquent\ModelNotFoundException::class,
    \Illuminate\Validation\ValidationException::class,
];

Render Method

The render method converts an exception into an HTTP response. By default it delegates to the parent, but you can return custom responses for specific exception types:

/**
 * Convert 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 CustomException) {
        return response()->view('errors.custom', [], 500);
    }
    return parent::render($request, $exception);
}

Reportable & Renderable Exceptions

You can define report and render directly on a custom exception class. Laravel will automatically invoke these methods:

<?php

namespace App\Exceptions;

use Exception;

class RenderException extends Exception
{
    /**
     * Report the exception.
     */
    public function report()
    {
        // custom reporting logic
    }

    /**
     * Render the exception into an HTTP response.
     */
    public function render($request)
    {
        return response(...);
    }
}

Tip: Declare report with required parameters and Laravel’s service container will inject them automatically.

HTTP Exceptions

Laravel provides the abort helper to generate HTTP error responses from anywhere in the application. For example:

abort(404);

You can also supply a custom message:

abort(403, 'Unauthorized action.');

Custom HTTP Error Pages

To customize error pages, create a Blade view matching the HTTP status code, e.g., resources/views/errors/404.blade.php. The exception instance is passed to the view as $exception:

<h2>{{ $exception->getMessage() }}</h2>

Publish the default error templates with:

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