Laravel integration guide

Add Bugsnag to your application to automatically detect handled and unhandled Laravel errors.

New to Bugsnag? Create an account

This library supports Laravel 5+ running PHP 5.5+. To integrate with older versions of Laravel and PHP, check out our legacy integration.


Add bugsnag/bugsnag-laravel to your composer.json:

$ composer require "bugsnag/bugsnag-laravel:^2.0"

Register our service provider in providers array in config/app.php before your AppServiceProvider::class:

'providers' => [
    // ...
    // ...

To use the configured Bugsnag client, import the facade each time:

use Bugsnag\BugsnagLaravel\Facades\Bugsnag;

Optionally, you can register an alias in config/app.php:

'aliases' => [
    // ...
    'Bugsnag' => Bugsnag\BugsnagLaravel\Facades\Bugsnag::class,

Basic configuration

Configure your Bugsnag API Key in your .env file:


You can find your API key in Project Settings from your Bugsnag dashboard.

If you’d like to configure Bugsnag further, create and edit a config/bugsnag.php file by running:

$ php artisan vendor:publish

For a list of available options, see the configuration options reference.

Reporting unhandled exceptions

Laravel 5.6+

To ensure all unhandled exceptions are sent to Bugsnag, set up a bugsnag logging channel and add it to your logging stack in config/logging.php:

    'channels' => [
        'stack' => [
            'driver' => 'stack',
            // Add bugsnag to the stack:
            'channels' => ['single', 'bugsnag'],

        // ...

        // Create a bugsnag logging channel:
        'bugsnag' => [
            'driver' => 'bugsnag',

At this point, Bugsnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your Bugsnag dashboard.

Note: Exceptions are not reported when running in the Tinker shell.

Laravel 5.0-5.5

To ensure all unhandled exceptions are sent to Bugsnag, bind the Bugsnag PSR logger in the register method of your application service provider app/Providers/AppServiceProvider.php:

$this->app->alias('bugsnag.logger', \Illuminate\Contracts\Logging\Log::class);
$this->app->alias('bugsnag.logger', \Psr\Log\LoggerInterface::class);

If you’d like to keep logging to your original logger as well as Bugsnag, you can bind 'bugsnag.multi' rather than 'bugsnag.logger'.

$this->app->alias('bugsnag.multi', \Illuminate\Contracts\Logging\Log::class);
$this->app->alias('bugsnag.multi', \Psr\Log\LoggerInterface::class);

At this point, Bugsnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your Bugsnag dashboard.

Note: Exceptions are not reported when running in the Tinker shell.

Reporting out of memory exceptions

Bugsnag can increase the PHP memory limit when your app runs out of memory to ensure events can be delivered. To do this, a “bootstrapper” class must be registered in both the app/Http/Kernel.php and app/Console/Kernel.php files:

protected function bootstrappers()
    return array_merge(

The OomBootstrapper must be the first registered bootstrapper, or it may not be called before the out of memory exception crashes your app.

The amount of extra memory Bugsnag allocates can be controlled with the memory limit increase option.

Reporting handled exceptions

Reporting handled exceptions can be accomplished as follows:

try {
    // Some potentially crashy code
} catch (Exception $ex) {

When reporting handled exceptions, it’s often helpful to send us custom diagnostic data or to adjust the severity of particular errors. For more information, see reporting handled errors.

Note: Exceptions are not reported when running in the Tinker shell.

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture the following data for every exception:

  • A full stacktrace
  • Request information, including ip, headers, URL, HTTP method, and HTTP params
  • Session, cookie, and user data
  • Release stage (production, beta, staging, etc)
  • Hostname

Custom diagnostics

In order to quickly reproduce and fix errors, it is often helpful to send additional application-specific diagnostic data to Bugsnag. This can be accomplished by registering a function to be executed before an error report is sent:

Bugsnag::registerCallback(function ($report) {
        'account' => [
            'name' => 'Acme Co.',
            'paying_customer' => true,

For more information, see the customizing error reports reference.

In Laravel callbacks should be registered within the boot function of your AppServiceProvider class:

public function boot()
    Bugsnag::registerCallback(function($report) {

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatically captured breadcrumbs

Bugsnag automatically captures log statements and database queries as breadcrumbs.

See the configuration options to modify this behavior.

Attaching custom breadcrumbs

Leaving breadcrumbs can be accomplished by using leaveBreadcrumb as follows:

Bugsnag::leaveBreadcrumb('Something happened!');

You can optionally attach a type and metadata to a breadcrumb for additional context into the state of the application when the breadcrumb was captured. See the Breadcrumb class for the available types.

    'Something happened!',

And with additional diagnostic metadata:

    'Something happened!',
    ['foo' => 'bar']

The metadata should only be one level deep.

Attaching breadcrumbs from events

Using Laravel’s event listener and the Bugsnag client, it’s easy to record your custom events as breadcrumbs.

For example, to record writing to the cache as a breadcrumb:

Event::listen('Illuminate\Cache\Events\KeyWritten', function ($event) {
    Bugsnag::leaveBreadcrumb('Cache written', 'process', [
        'key' => $event->key,
        'value' => $event->value,
        'ttl' => "{$event->minutes}mins",

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard.

If you are using Laravel’s built-in authentication, we will automatically capture information about the currently authenticated user.

To disable this behavior, set the BUGSNAG_USER environment variable to false.

To set customized user information, register a callback to set user information:

Bugsnag::registerCallback(function ($report) {
        'id' => '123456',
        'name' => 'Leeroy Jenkins',
        'email' => '',

For more information, see configuration options.

Session tracking

Bugsnag can track the number of “sessions” that happen in your application. This enables Bugsnag to provide and compare stability scores between releases to help you understand the quality of your releases. This functionality is disabled by default, but can be enabled through the configuration:


Using this option, Bugsnag will report a session each time Laravel processes a request.

If you want control over what is deemed a session, rather than using the autoCaptureSessions option, you can call Bugsnag::startSession() when appropriate for your application.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the Bugsnag client. You can use the Features dashboard to identify whether these features have introduced errors into your app.

Bugsnag::addFeatureFlag('Checkout button color', 'Blue')
Bugsnag::addFeatureFlag('New checkout flow')

For more information, see Feature flags & experiments.

Tracking releases

By sending your source revision or application version to us when you release a new version of your app, you’ll be able to see in which release each error was introduced.

You must configure the version your app, see the App Version configuration option for more details:


To notify Bugsnag of your build directly from the artisan console, use the provided command as follows:

Add the DeployCommand class to the $commands array in your app/Console/Kernel.php file:

protected $commands = [
    // ...

Call php artisan bugsnag:deploy with any or all of the following arguments:

  • --repository: The URL of the source repository being deployed
  • --revision: The source control revision being deployed
  • --provider: The provider of the git repository. Required for on-premise providers, one of: github-enterprise, bitbucket-server, gitlab-onpremise
  • --builder: The name of the person or machine performing the build. Defaults to whoami

For example:

php artisan bugsnag:deploy \
  --repository "" \
  --revision "ef7bebf8bdb1919d947afe46ab4b2fb4278039b3" \
  --builder "MyExampleUser"

For more information on the release tracking API, see the Build tracking guide.

Alternatively take a look at our other build-tool integrations.

Next steps