Laravel 12: Understanding Error and Exception Handling with Examples

When building web applications, handling errors and exceptions is crucial to ensure a smooth user experience and maintain the stability of your application. Laravel, a popular PHP framework, provides a robust system for managing errors and exceptions. In this blog, we'll explore how Laravel 12 handles errors, how you can customize error reporting and rendering, and how to create custom error pages.

---

Introduction to Error Handling in Laravel 12

When you start a new Laravel 12 project, error and exception handling is already configured for you. Laravel 12 uses the withExceptions method in the bootstrap/app.php file to manage how exceptions are reported and rendered. The $exceptions object passed to this method is an instance of Illuminate\Foundation\Configuration\Exceptions, which is responsible for handling exceptions in your application.

---

Configuration

Laravel's error handling behavior is controlled by the debug option in the config/app.php file. This option determines how much information about an error is displayed to the user. During development, you should set the APP_DEBUG environment variable to true in your .env file. However, in production, this value should always be false to avoid exposing sensitive information to users.

---

Reporting Exceptions

Laravel 12 allows you to log exceptions or send them to external services like Sentry or Flare. By default, exceptions are logged based on your logging configuration, but you can customize this behavior.

Custom Exception Reporting

You can register a custom exception reporting callback using the report method in your bootstrap/app.php file. For example, if you want to handle an InvalidOrderException differently, you can do so like this:

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (InvalidOrderException $e) {
        // Custom reporting logic here
    });
});
  

If you want to stop Laravel from logging the exception after your custom logic, you can use the stop method or return false from the callback.

$exceptions->report(function (InvalidOrderException $e) {
    // Custom reporting logic here
})->stop();
  

---

Rendering Exceptions

Laravel automatically converts exceptions into HTTP responses. However, you can customize how specific exceptions are rendered by using the render method.

Custom Exception Rendering

For example, if you want to render a custom view for an InvalidOrderException, you can do so like this:

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 can also customize the rendering of built-in exceptions like NotFoundHttpException:

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

---

Custom HTTP Error Pages

Laravel makes it easy to create custom error pages for different HTTP status codes. For example, to create a custom 404 error page, you can create a resources/views/errors/404.blade.php file. This view will be rendered whenever a 404 error occurs.

Here’s an example of a custom 404 error page:

<h2>{{ $exception->getMessage() }}</h2>
<p>Sorry, the page you are looking for could not be found.</p>
  

You can also define fallback error pages for a series of HTTP status codes. For example, you can create a 4xx.blade.php file to handle all 4xx errors and a 5xx.blade.php file to handle all 5xx errors.

---

Throttling Reported Exceptions

If your application generates a large number of exceptions, you may want to throttle how many are logged or sent to external services. Laravel allows you to sample exceptions randomly or rate-limit them.

Random Sampling

You can use the throttle method to randomly sample exceptions:

use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->throttle(function (Throwable $e) {
        return Lottery::odds(1, 1000); // Sample 1 out of 1000 exceptions
    });
});
  

Rate Limiting

Alternatively, you can rate-limit exceptions using the Limit class:

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); // Limit to 300 exceptions per minute
        }
    });
});
  

---

Conclusion

Laravel 12 provides a powerful and flexible system for handling errors and exceptions. By customizing exception reporting, rendering, and error pages, you can ensure that your application handles errors gracefully and provides a better user experience. Whether you're logging exceptions, rendering custom error pages, or throttling error reports, Laravel has you covered.

By following the examples and techniques outlined in this blog, you can take full control of error handling in your Laravel application and ensure that it remains stable and user-friendly, even when things go wrong.