Add Bugsnag error monitoring to your Symfony applications.
This library supports Symfony versions 2, 3, 4 and 5, running PHP 5.5+.
This guide is for Symfony 4 and 5. You can find information on how to get started with Symfony versions 2 and 3 in the legacy Symfony section.
Add bugsnag/bugsnag-symfony to your composer.json:
$ composer require "bugsnag/bugsnag-symfony:^1.6"
The Bugsnag bundle will automatically be registered in your config/bundles.php file.
To associate your application with a project in your Bugsnag dashboard, you’ll need to set your Integration API Key in your config/packages/bugsnag.yaml file:
bugsnag:
api_key: YOUR-API-KEY-HERE
You can find your API key in Project Settings from your Bugsnag dashboard.
For a list of available options, see the configuration options reference.
In order to manually use the Bugsnag client in any of your controllers you will need to acquire it from the service container.
In a controller extending a Symfony Controller:
$this->get('bugsnag')->notifyException(
new Exception('Example exception!')
);
In a controller extending an AbstractController, the service can be acquired via Symfony’s dependency injection component following information in that guide.
After completing installation and basic configuration, unhandled exceptions in your Symfony app will be automatically reported to your Bugsnag dashboard.
Bugsnag will increase the PHP memory limit when your app runs out of memory to ensure events can be delivered.
This is enabled by default as part of the basic configuration steps. To disable this, or change the amount of extra memory Bugsnag allocates, see the memory limit increase configuration option.
This feature relies on Symfony’s ErrorHandler component, which was added in Symfony 4.4. Older versions of Symfony use the Debug component, which does not inform Bugsnag of out of memory exceptions.
Reporting handled exceptions can be accomplished as follows:
try {
// Some potentially crashy code
} catch (Exception $ex) {
$this->get('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.
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.
In Symfony 4 and 5 application-wide callbacks should be registered within the boot function of your src/Kernel.php file:
public function boot()
{
parent::boot();
$this->container->get('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.
Leaving breadcrumbs can be accomplished by using leaveBreadcrumb as follows:
$this->get('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.
$this->get('bugsnag')->leaveBreadcrumb(
'Something happened!',
\Bugsnag\Breadcrumbs\Breadcrumb::ERROR_TYPE
);
And with additional diagnostic metadata:
$this->get('bugsnag')->leaveBreadcrumb(
'Something happened!',
\Bugsnag\Breadcrumbs\Breadcrumb::MANUAL_TYPE,
['foo' => 'bar']
);
The metadata should only be one level deep.
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 Symfony’s built-in authentication, we will automatically capture information about the currently authenticated user.
To disable this behavior, set user to false during configuration.
To set customized user information, register a callback and update the report object:
$this->get('bugsnag')->registerCallback(function ($report) {
$report->setUser([
'id' => '123456',
'name' => 'Leeroy Jenkins',
'email' => 'leeeeroy@jenkins.com',
]);
});
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.
$this->get('bugsnag')->addFeatureFlag('Checkout button color', 'Blue')
$this->get('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:
$this->get('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 by calling $this->get('bugsnag')->build() or you can call our Build API directly.
For more information, see our PHP Build Integrations guide.
bugsnag-symfony and bugsnag-php, the open-source libraries powering Bugsnag for Symfony, on GitHub