Introduction
When you start a new Laravel project, error and exception
handling is already configured for you; however, at any
point, you may use the withExceptions
method in your application's
bootstrap/app.php to manage how exceptions
are reported and rendered by your application.
The $exceptions object provided to the
withExceptions closure is an instance of
Illuminate\Foundation\Configuration\Exceptions
and is responsible for managing exception handling in
your application. We'll dive deeper into this object
throughout this documentation.
Configuration
The debug option in your
config/app.php configuration file
determines how much information about an error is
actually displayed to the user. By default, this option
is set to respect the value of the
APP_DEBUG environment variable, which is
stored in your .env file.
During local development, you should set the
APP_DEBUG environment variable to
true. In your production
environment, this value should always be
false. If the value is set to
true in production, you risk exposing
sensitive configuration values to your application's
end users.
Handling Exceptions
Reporting Exceptions
In Laravel, exception reporting is used to log exceptions or send them to an external service Sentry or Flare. By default, exceptions will be logged based on your logging configuration. However, you are free to log exceptions however you wish.
If you need to report different types of exceptions in
different ways, you may use the report
exception method in your application's
bootstrap/app.php to register a closure
that should be executed when an exception of a given
type needs to be reported. Laravel will determine what
type of exception the closure reports by examining the
type-hint of the closure:
->withExceptions(function (Exceptions $exceptions) {
$exceptions->report(function (InvalidOrderException $e) {
// ...
});
})
When you register a custom exception reporting callback
using the report method, Laravel will still
log the exception using the default logging
configuration for the application. If you wish to stop
the propagation of the exception to the default logging
stack, you may use the stop method when
defining your reporting callback or return
false from the callback:
->withExceptions(function (Exceptions $exceptions) {
$exceptions->report(function (InvalidOrderException $e) {
// ...
})->stop();
$exceptions->report(function (InvalidOrderException $e) {
return false;
});
})
Note:
To customize the exception reporting for a given exception, you may also utilize reportable exceptions.
Global Log Context
If available, Laravel automatically adds the current
user's ID to every exception's log message as contextual
data. You may define your own global contextual data
using the context exception method in your
application's bootstrap/app.php file. This
information will be included in every exception's log
message written by your application:
->withExceptions(function (Exceptions $exceptions) {
$exceptions->context(fn () => [
'foo' => 'bar',
]);
})
Exception Log Context
While adding context to every log message can be useful,
sometimes a particular exception may have unique context
that you would like to include in your logs. By defining
a context method on one of your
application's exceptions, you may specify any data
relevant to that exception that should be added to the
exception's log entry:
<?php
namespace App\Exceptions;
use Exception;
class InvalidOrderException extends Exception
{
// ...
/**
* Get the exception's context information.
*
* @return array<string, mixed>
*/
public function context(): array
{
return ['order_id' => $this->orderId];
}
}
The report Helper
Sometimes you may need to report an exception but
continue handling the current request. The
report helper function allows you to
quickly report an exception without rendering an error
page to the user:
public function isValid(string $value): bool
{
try {
// Validate the value...
} catch (Throwable $e) {
report($e);
return false;
}
}
Deduplicating Reported Exceptions
If you are using the report function
throughout your application, you may occasionally report
the same exception multiple times, creating duplicate
entries in your logs.
If you would like to ensure that a single instance of an
exception is only ever reported once, you may invoke the
dontReportDuplicates exception method in
your application's bootstrap/app.php
file:
->withExceptions(function (Exceptions $exceptions) {
$exceptions->dontReportDuplicates();
})
Now, when the report helper is called with
the same instance of an exception, only the first call
will be reported:
$original = new RuntimeException('Whoops!');
report($original); // reported
try {
throw $original;
} catch (Throwable $caught) {
report($caught); // ignored
}
report($original); // ignored
report($caught); // ignored
Exception Log Levels
When messages are written to your application's logs, the messages are written at a specified log level, which indicates the severity or importance of the message being logged.
As noted above, even when you register a custom exception
reporting callback using the report method,
Laravel will still log the exception using the default
logging configuration for the application; however,
since the log level can sometimes influence the channels
on which a message is logged, you may wish to configure
the log level that certain exceptions are logged at.
To accomplish this, you may use the level
exception method in your application's
bootstrap/app.php file. This method
receives the exception type as its first argument and
the log level as its second argument:
use PDOException;
use Psr\Log\LogLevel;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->level(PDOException::class, LogLevel::CRITICAL);
})
Ignoring Exceptions by Type
When building your application, there will be some types
of exceptions you never want to report. To ignore these
exceptions, you may use the dontReport
exception method in your application's
bootstrap/app.php file. Any class provided
to this method will never be reported; however, they may
still have custom rendering logic:
use App\Exceptions\InvalidOrderException;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->dontReport([
InvalidOrderException::class,
]);
})
Internally, Laravel already ignores some types of errors
for you, such as exceptions resulting from 404 HTTP
errors or 419 HTTP responses generated by invalid CSRF
tokens. If you would like to instruct Laravel to stop
ignoring a given type of exception, you may use the
stopIgnoring exception method in your
application's bootstrap/app.php file:
use Symfony\Component\HttpKernel\Exception\HttpException;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->stopIgnoring(HttpException::class);
})
Rendering Exceptions
By default, the Laravel exception handler will convert
exceptions into an HTTP response for you. However, you
are free to register a custom rendering closure for
exceptions of a given type. You may accomplish this by
using the render exception method in your
application's bootstrap/app.php file.
The closure passed to the render method
should return an instance of
Illuminate\Http\Response, which may be
generated via the response helper. Laravel
will determine what type of exception the closure
renders by examining the type-hint of the closure:
use App\Exceptions\InvalidOrderException;
use Illuminate\Http\Request;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->render(function (InvalidOrderException $e, Request $request) {
return response()->view('errors.invalid-order', [], 500);
});
})
You may also use the render method to
override the rendering behavior for built-in Laravel or
Symfony exceptions such as
NotFoundHttpException. If the closure given
to the render method does not return a
value, Laravel's default exception rendering will be
utilized:
use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->render(function (NotFoundHttpException $e, Request $request) {
if ($request->is('api/*')) {
return response()->json([
'message' => 'Record not found.'
], 404);
}
});
})
Rendering Exceptions as JSON
When rendering an exception, Laravel will automatically
determine if the exception should be rendered as an HTML
or JSON response based on the Accept header
of the request. If you would like to customize how
Laravel determines whether to render HTML or JSON
exception responses, you may utilize the
shouldRenderJsonWhen method:
use Illuminate\Http\Request;
use Throwable;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
if ($request->is('admin/*')) {
return true;
}
return $request->expectsJson();
});
})
Customizing the Exception Response
Rarely, you may need to customize the entire HTTP
response rendered by Laravel's exception handler. To
accomplish this, you may register a response
customization closure using the respond
method:
use Symfony\Component\HttpFoundation\Response;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->respond(function (Response $response) {
if ($response->getStatusCode() === 419) {
return back()->with([
'message' => 'The page expired, please try again.',
]);
}
return $response;
});
})
Reportable and Renderable Exceptions
Instead of defining custom reporting and rendering
behavior in your application's
bootstrap/app.php file, you may define
report and render methods
directly on your application's exceptions. When these
methods exist, they will automatically be called by the
framework:
<?php
namespace App\Exceptions;
use Exception;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
class InvalidOrderException extends Exception
{
/**
* Report the exception.
*/
public function report(): void
{
// ...
}
/**
* Render the exception into an HTTP response.
*/
public function render(Request $request): Response
{
return response(/* ... */);
}
}
If your exception extends an exception that is already
renderable, such as a built-in Laravel or Symfony
exception, you may return false from the
exception's render method to render the
exception's default HTTP response:
/**
* Render the exception into an HTTP response.
*/
public function render(Request $request): Response|bool
{
if (/** Determine if the exception needs custom rendering */) {
return response(/* ... */);
}
return false;
}
If your exception contains custom reporting logic that is
only necessary when certain conditions are met, you may
need to instruct Laravel to sometimes report the
exception using the default exception handling
configuration. To accomplish this, you may return
false from the exception's
report method:
/**
* Report the exception.
*/
public function report(): bool
{
if (/** Determine if the exception needs custom reporting */) {
// ...
return true;
}
return false;
}
Note:
You may type-hint any required dependencies of thereportmethod and they will automatically be injected into the method by Laravel's service container.
Throttling Reported Exceptions
If your application reports a very large number of exceptions, you may want to throttle how many exceptions are actually logged or sent to your application's external error tracking service.
To take a random sample rate of exceptions, you may use
the throttle exception method in your
application's bootstrap/app.php file. The
throttle method receives a closure that
should return a Lottery instance:
use Illuminate\Support\Lottery;
use Throwable;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->throttle(function (Throwable $e) {
return Lottery::odds(1, 1000);
});
})
It is also possible to conditionally sample based on the
exception type. If you would like to only sample
instances of a specific exception class, you may return
a Lottery instance only for that class:
use App\Exceptions\ApiMonitoringException;
use Illuminate\Support\Lottery;
use Throwable;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->throttle(function (Throwable $e) {
if ($e instanceof ApiMonitoringException) {
return Lottery::odds(1, 1000);
}
});
})
You may also rate limit exceptions logged or sent to an
external error tracking service by returning a
Limit instance instead of a
Lottery. This is useful if you want to
protect against sudden bursts of exceptions flooding
your logs, for example, when a third-party service used
by your application is down:
use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Throwable;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->throttle(function (Throwable $e) {
if ($e instanceof BroadcastException) {
return Limit::perMinute(300);
}
});
})
By default, limits will use the exception's class as the
rate limit key. You can customize this by specifying
your own key using the by method on the
Limit:
use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Throwable;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->throttle(function (Throwable $e) {
if ($e instanceof BroadcastException) {
return Limit::perMinute(300)->by($e->getMessage());
}
});
})
Of course, you may return a mixture of
Lottery and Limit instances
for different exceptions:
use App\Exceptions\ApiMonitoringException;
use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Lottery;
use Throwable;
->withExceptions(function (Exceptions $exceptions) {
$exceptions->throttle(function (Throwable $e) {
return match (true) {
$e instanceof BroadcastException => Limit::perMinute(300),
$e instanceof ApiMonitoringException => Lottery::odds(1, 1000),
default => Limit::none(),
};
});
})
HTTP Exceptions
Some exceptions describe HTTP error codes from the
server. For example, this may be a "page not
found" error (404), an "unauthorized
error" (401), or even a developer generated 500
error. In order to generate such a response from
anywhere in your application, you may use the
abort helper:
abort(404);
Custom HTTP Error Pages
Laravel makes it easy to display custom error pages for
various HTTP status codes. For example, to customize the
error page for 404 HTTP status codes, create a
resources/views/errors/404.blade.php view
template. This view will be rendered for all 404 errors
generated by your application. The views within this
directory should be named to match the HTTP status code
they correspond to. The
Symfony\Component\HttpKernel\Exception\HttpException
instance raised by the abort function will
be passed to the view as an $exception
variable:
<h2>{{ $exception->getMessage() }}</h2>
You may publish Laravel's default error page templates
using the vendor:publish Artisan command.
Once the templates have been published, you may
customize them to your liking:
php artisan vendor:publish --tag=laravel-errors
Fallback HTTP Error Pages
You may also define a "fallback" error page for
a given series of HTTP status codes. This page will be
rendered if there is not a corresponding page for the
specific HTTP status code that occurred. To accomplish
this, define a 4xx.blade.php template and a
5xx.blade.php template in your
application's resources/views/errors
directory.