You are on page 1of 7

Errors & Logging

Introduction
Configuration
Error Detail
Log Storage
Log Severity Levels
Custom Monolog Configuration
The Exception Handler
Report Method
Render Method
Reportable & Renderable Exceptions
HTTP Exceptions
Custom HTTP Error Pages
Logging

Introduction
When you start a new Laravel project, error and exception handling is already configured for you. The
App\Exceptions\Handler class is where all exceptions triggered by your application are logged and then
rendered back to the user. We'll dive deeper into this class throughout this documentation.

For logging, Laravel utilizes the Monolog library, which provides support for a variety of powerful log
handlers. Laravel configures several of these handlers for you, allowing you to choose between a
single log file, rotating log files, or writing error information to the system log.

Configuration
Error Detail

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.

For 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.

Log Storage

Out of the box, Laravel supports writing log information to single files, daily files, the syslog , and
the errorlog . To configure which storage mechanism Laravel uses, you should modify the log

1 of 7
option in your config/app.php configuration file. For example, if you wish to use daily log files instead
of a single file, you should set the log value in your app configuration file to daily :

'log' => 'daily'

Maximum Daily Log Files

When using the log mode, Laravel will only retain five days of log files by default. If you want to
daily

adjust the number of retained files, you may add a log_max_files configuration value to your app
configuration file:

'log_max_files' => 30

Log Severity Levels

When using Monolog, log messages may have different levels of severity. By default, Laravel writes all
log levels to storage. However, in your production environment, you may wish to configure the
minimum severity that should be logged by adding the log_level option to your app.php
configuration file.

Once this option has been configured, Laravel will log all levels greater than or equal to the specified
severity. For example, a default log_level of error will log error, critical, alert, and emergency
messages:

'log_level' => env('APP_LOG_LEVEL', 'error'),

Monolog recognizes the following severity levels - from least severe to most severe: debug ,
info , notice , warning , error , critical , alert , emergency .

Custom Monolog Configuration

If you would like to have complete control over how Monolog is configured for your application, you
may use the application's configureMonologUsing method. You should place a call to this method in
your bootstrap/app.php file right before the $app variable is returned by the file:

$app->configureMonologUsing(function ($monolog) {
$monolog->pushHandler(...);
});

return $app;

Customizing The Channel Name

2 of 7
By default, Monolog is instantiated with name that matches the current environment, such as
production or local . To change this value, add the log_channel option to your app.php configuration
file:

'log_channel' => env('APP_LOG_CHANNEL', 'my-app-name'),

The Exception Handler


The Report Method

All exceptions are handled by the App\Exceptions\Handler class. This class contains two methods:
report and render . We'll examine each of these methods in detail. The report method is used to log
exceptions or send them to an external service like Bugsnag or Sentry. By default, the report method
simply passes the exception to the base class where the exception is logged. However, you are free to
log exceptions however you wish.

For example, if you need to report different types of exceptions in different ways, you may use the
PHP instanceof comparison operator:

/**
* 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)
{
if ($exception instanceof CustomException) {
//
}

return parent::report($exception);
}

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 using your exception handler's
report method without rendering an error page:

public function isValid($value)


{
try {
// Validate the value...
} catch (Exception $e) {

3 of 7
report($e);

return false;
}
}

Ignoring Exceptions By Type

The property of the exception handler contains an array of exception types that will not
$dontReport

be logged. For example, exceptions resulting from 404 errors, as well as several other types of errors,
are not written to your log files. You may add other exception types to this array as needed:

/**
* 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\Validation\ValidationException::class,
];

The Render Method

The method is responsible for converting a given exception into an HTTP response that
render

should be sent back to the browser. By default, the exception is passed to the base class which
generates a response for you. However, you are free to check the exception type or return your own
custom response:

/**
* 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 CustomException) {
return response()->view('errors.custom', [], 500);
}

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


}

Reportable & Renderable Exceptions


4 of 7
Instead of type-checking exceptions in the exception handler's report and render methods, you may
define report and render methods directly on your custom exception. When these methods exist,
they will be called automatically by the framework:

<?php

namespace App\Exceptions;

use Exception;

class RenderException 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(...);
}
}

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

The abort helper will immediately raise an exception which will be rendered by the exception
handler. Optionally, you may provide the response text:

abort(403, 'Unauthorized action.');

Custom HTTP Error Pages


5 of 7
Laravel makes it easy to display custom error pages for various HTTP status codes. For example, if you
wish to customize the error page for 404 HTTP status codes, create a
resources/views/errors/404.blade.php . This file will be served on 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 HttpException instance raised by the abort function will be passed to the view as
an $exception variable:

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

Logging
Laravel provides a simple abstraction layer on top of the powerful Monolog library. By default, Laravel
is configured to create a log file for your application in the storage/logs directory. You may write
information to the logs using the Log facade:

<?php

namespace App\Http\Controllers;

use App\User;
use Illuminate\Support\Facades\Log;
use App\Http\Controllers\Controller;

class UserController extends Controller


{
/**
* Show the profile for the given user.
*
* @param int $id
* @return Response
*/
public function showProfile($id)
{
Log::info('Showing user profile for user: '.$id);

return view('user.profile', ['user' => User::findOrFail($id)]);


}
}

The logger provides the eight logging levels defined in RFC 5424: emergency, alert, critical, error,
warning, notice, info and debug.

Log::emergency($message);
Log::alert($message);
Log::critical($message);
Log::error($message);
Log::warning($message);
Log::notice($message);

6 of 7
Log::info($message);
Log::debug($message);

Contextual Information

An array of contextual data may also be passed to the log methods. This contextual data will be
formatted and displayed with the log message:

Log::info('User failed to login.', ['id' => $user->id]);

Accessing The Underlying Monolog Instance

Monolog has a variety of additional handlers you may use for logging. If needed, you may access the
underlying Monolog instance being used by Laravel:

$monolog = Log::getMonolog();

7 of 7