Laravel Exception & Error Tracking

Typical installation time: 5 minutes

Hi there! You've found Honeybadger's guide to Laravel error and exception tracking. Once installed, Honeybadger will automatically report errors wherever they may happen:

During a web request
In a scheduled command
In a background task
When a process crashes

On this page:

Installation
Identifying Users
Adding Context
Check-Ins
Using Honeybadger as a Logger
Display Honeybadger Errors for resources in Laravel Nova

Installation

First, install the honeybadger-laravel package via composer:

bash

composer require honeybadger-io/honeybadger-laravel

Laravel Version Support

Install the version of our package based on the version of Laravel you are using:

Laravel Version	Honeybadger Laravel Version
11.x	4.x (current)
10.x	4.x (current)
9.x	3.13.x
8.x	3.2.x
7.x	3.x
6.x	2.x
5.x	1.x

Note: This package uses Laravel's package discovery to register the service provider and facade to the framework. If you are using an older version of Laravel or do not use package discovery, you may need to manually register those components.

Next, add Honeybadger reporting to Laravel 11 and later by adding the following to bootstrap/app.php (https://laravel.com/docs/11.x/errors#reporting-exceptions):

php
bootstrap/app.php

  

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->reportable(static function (Throwable $e) {
        if (app()->bound('honeybadger')) {
            app('honeybadger')->notify($e, app('request'));
        }
    });
})

In Laravel 8.5 to 10, the default handler comes with a register() method; you should add the Honeybadger client within the reportable() callback.

php
app/Exceptions/Handler.php

  

public function register()
{
    $this->reportable(function (Throwable $e) {
        if (app()->bound('honeybadger')) {
            app('honeybadger')->notify($e, app('request'));
        }
    });
}

On earlier versions of Laravel, add the client within the report($exception) method:

php

  

public function report(Throwable $exception)
{
    if (app()->bound('honeybadger') && $this->shouldReport($exception)) {
        app('honeybadger')->notify($exception, app('request'));
    }
    parent::report($exception);
}

Finally, run the honeybadger:install artisan command:

bash

php artisan honeybadger:install [Your project API key]

The honeybadger:install command does three things:

Adds HONEYBADGER_API_KEY to .env and .env.example
Creates Honeybadger's config/honeybadger.php configuration file
Sends a test notification to your Honeybadger project

If everything is set up correctly, you should now have an error report in Honeybadger!

Note: The default config for Laravel won't report errors to Honeybadger on local and testing environments. You can change that with the report_data option.

Identifying Users and Controller/Action

Honeybadger automatically captures details about the current logged-in user, as well as the controller and method name. No extra configuration needed. We only capture the user ID, so no sensitive information is transmitted.

When an error occurs, you'll see an Affected Users section on your dashboard, where we'll list the user IDs and how many times they encountered the error.

Adding Context

Context can be added by either the provided Facade or by resolving from the service container.

Facade

php

Honeybadger::context('key', $value);

DI Resolution

php

  

use Honeybadger\Honeybadger;

public function __construct(Honeybadger $honeybadger)
{
    $honeybadger->context('key', $value);
}

Helper Resolution

php

  

use Honeybadger\Honeybadger;

public function __construct()
{
    app('honeybadger')->context('key', $value);
    app(Honeybadger::class)->context('key', $value)
}

Check-Ins

honeybadger-laravel integrates with Honeybadger's Check-In feature to help you know when your scheduled tasks and background jobs go missing or silently fail.

To get started, create a new check-in in the Check-Ins tab of your project dashboard. You'll be given a check-in URL that looks like this: https://api.honeybadger.io/v1/check_in/Jiy63Xw. Take note of the check-in ID; it's the last part of the check-in URL. In this example, it's Jiy63Xw. Alternatively, you can setup your check-ins entirely within your configuration file. If you follow this method, you don't need the check-in ID anymore and instead you can use the check-in slug.

Run a one-off check-in

To run a one-off check-in, use the honeybadger:checkin command with your check-in ID. This will let Honeybadger know that your app is alive.

bash

php artisan honeybadger:checkin Jiy63Xw

Or if you have configured your check-ins in your configuration file:

bash

php artisan honeybadger:checkin "my-checkin"

Scheduled Command

You can schedule the check-in command to run at an interval. This method is great for ensuring your application is up and running.

php
app/Console/Kernel.php

  

protected function schedule(Schedule $schedule)
{
    $schedule->command('honeybadger:checkin Jiy63Xw')->everyFiveMinutes();
    // or using the check-in slug
    $schedule->command('honeybadger:checkin "my-checkin"')->everyFiveMinutes();
}

After a Scheduled Command

You can use the thenPingHoneybadger($checkInId) macro to check-in after certain scheduled commands are run. This method is great for making sure specific scheduled commands are running on time.

php
app/Console/Kernel.php

  

protected function schedule(Schedule $schedule)
{
    $schedule->command(SendEmails::class)->daily()
        ->thenPingHoneybadger('Jiy63Xw');
        // or using the check-in slug
        ->thenPingHoneybadger('my-checkin');
}

In this example, if SendEmails fails to run for some reason, Honeybadger will notify you.

You can also specify the environments where the check-in is allowed to run:

php
app/Console/Kernel.php

  

protected function schedule(Schedule $schedule)
{
    $schedule->command(SendEmails::class)->daily()
        ->thenPingHoneybadger('Jiy63Xw', 'production');
        // or using the check-in slug
        ->thenPingHoneybadger('my-checkin', 'production');
    $schedule->command(CheckStatus::class)->daily()
        ->thenPingHoneybadger('Jiy63Xw', ['production', 'staging']);
        // or using the check-in slug
        ->thenPingHoneybadger('my-checkin', ['production', 'staging']);
}

After a Successful Scheduled Command

You can use the pingHoneybadgerOnSuccess($checkInId) macro to ensure that a certain command was run and completed successfully. This method is great for making sure specific scheduled commands are running on time only if it was successful. Like the thenPingHoneybadger method, you can also restrict it to specific environments.

php
app/Console/Kernel.php

  

protected function schedule(Schedule $schedule)
{
    $schedule->command(SendEmails::class)->daily()
        ->pingHoneybadgerOnSuccess('Jiy63Xw', 'production');
        // or using the check-in slug
        ->pingHoneybadgerOnSuccess('my-checkin', 'production');
}

Using Honeybadger as a Logger

Note: If you want to send your logs to Honeybadger, consider sending them to Insights instead. You can learn more here and enable the integration by following the instructions here.

If you prefer, you can also use Honeybadger as a log channel in your Laravel app. To do this, you'll need to register a custom channel in your config/logging.php, making use of the HoneybadgerLogDriver:

php
config/logging.php

  

    'channels' => [
        // ...
        'honeybadger' => [
            'driver'  => 'custom',
            'via' => Honeybadger\HoneybadgerLaravel\HoneybadgerLogDriver::class,
            'name' => 'honeybadger',
            'level' => 'error',
        ],
    ],

Now you can write log messages as normal with Laravel's log facade, and they'll show up on your Honeybadger dashboard.

php

Log::channel('honeybadger')->error('An error message');
Log::channel('honeybadger')->error('An error message with context', ["some-key" => "some-value"]);
Log::channel('honeybadger')->error($exception);

If you include an exception context item in your error messages, we'll automatically format them for easy viewing:

php

$e = new \Exception('Something happened');
Log::channel('honeybadger')->error('An error message', ['exception' => $e]);

You can also add the custom channel to your default stack so you can automatically have exceptions logged to Honeybadger as well:

php
config/logging.php

  

    'channels' => [
        'stack' => [
            'driver' => 'stack',
            'channels' => ['single', 'honeybadger'],
            'ignore_exceptions' => false,
        ],
        // ...
    ],

Package:
honeybadger-io/honeybadger-laravel

Version:
v4.3.0

Repository:
https://github.com/honeybadger-io/honeybadger-laravel