Add BugSnag to your application to automatically detect handled and unhandled Laravel errors.
This library supports Laravel 5+ running PHP 5.5+. To integrate with older versions of Laravel and PHP, check out our legacy integration.
New to BugSnag? Create an account
Looking for performance monitoring? See our performance guide
Add bugsnag/bugsnag-laravel to your composer.json:
$ composer require "bugsnag/bugsnag-laravel:^2.0"
The latest available version of bugsnag-laravel is v2.28.0.
Register our service provider in bootstrap/providers.php as the first provider:
return [
Bugsnag\BugsnagLaravel\BugsnagServiceProvider::class,
// ...
];
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' => Illuminate\Support\Facades\Facade::defaultAliases()->merge([
'Bugsnag' => Bugsnag\BugsnagLaravel\Facades\Bugsnag::class,
// ...
])->toArray(),
Register our service provider in providers array in config/app.php before your AppServiceProvider::class:
'providers' => [
// ...
Bugsnag\BugsnagLaravel\BugsnagServiceProvider::class,
// ...
],
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,
],
Configure your BugSnag API Key in your .env file:
BUGSNAG_API_KEY=your-api-key-here
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.
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.
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.
BugSnag can increase the PHP memory limit when your app runs out of memory to ensure events can be delivered. To do this call the OomBootstrapper in bootstrap/app.php before calling Application::configure:
(new \Bugsnag\BugsnagLaravel\OomBootstrapper())->bootstrap();
return Application::configure(basePath: dirname(__DIR__))
// ...
The amount of extra memory BugSnag allocates can be controlled with the memory limit increase option.
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(
[\Bugsnag\BugsnagLaravel\OomBootstrapper::class],
parent::bootstrappers(),
);
}
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 can be accomplished as follows:
try {
// Some potentially crashy code
} catch (Exception $ex) {
Bugsnag::notifyException($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.
The default logging channel is modified when running an app in Laravel Vapor. To ensure all unhandled exceptions are sent to BugSnag, configure a new vapor logging channel in config/logging.php:
'channels' => [
'vapor' => [
'driver' => 'stack',
// Add bugsnag to the stack:
'channels' => ['bugsnag', 'stderr'],
],
// ...
// Create a bugsnag logging channel:
'bugsnag' => [
'driver' => 'bugsnag',
],
],
Tell Laravel Vapor to use this new logging channel by editing the .env.production file:
LOG_CHANNEL=vapor
BugSnag will automatically capture the following data for every exception:
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) {
$report->setMetaData([
'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) {
...
});
}
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.
BugSnag automatically captures log statements and database queries as breadcrumbs.
See the configuration options to modify this behavior.
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.
Bugsnag::leaveBreadcrumb(
'Something happened!',
\Bugsnag\Breadcrumbs\Breadcrumb::ERROR_TYPE
);
And with additional diagnostic metadata:
Bugsnag::leaveBreadcrumb(
'Something happened!',
\Bugsnag\Breadcrumbs\Breadcrumb::MANUAL_TYPE,
['foo' => 'bar']
);
The metadata should only be one level deep.
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",
]);
});
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) {
$report->setUser([
'id' => '123456',
'name' => 'Leeroy Jenkins',
'email' => 'leeeeroy@jenkins.com',
]);
});
For more information, see configuration options.
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:
Bugsnag::setAutoCaptureSessions(true);
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.
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.
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.
Ensure you’ve set your app version within the application:
Bugsnag::setAppVersion('1.2.3');
You can then notify BugSnag of your build to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.
This can be done using our Laravel Artisan command or you can call our Build API directly.
bugsnag-laravel and bugsnag-php, the open-source libraries powering BugSnag for Laravel, on GitHub