Docs Platforms PHP Symfony Legacy
bugsnag.com Start Free Trial

Symfony integration guide

Add BugSnag error monitoring to your Symfony applications.

This library supports both Symfony 2 and 3, running PHP 5.5+.

This guide is for Symfony 2 and 3, for Symfony 4 and 5 support, please see the updated Symfony integration guide.

Installation

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

$ composer require "bugsnag/bugsnag-symfony:^1.0"

Then register the bundle in your kernel by adding it to the $bundles array in the registerBundles method:

$bundles = [
    // ...
    new Bugsnag\BugsnagBundle\BugsnagBundle(),
    // ...
];

Basic configuration

To associate your application with a project in your BugSnag dashboard, you’ll need to set your Integration API Key in your app/config/config.yml file:

bugsnag:
    api_key: YOUR-API-KEY-HERE

You can find this key immediately after creating a new project from your BugSnag dashboard, or later on your project’s settings page.

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

Accessing BugSnag’s client

The BugSnag client can be resolved from Symfony’s service container using the alias bugsnag. The full class name is Bugsnag\Client.

If you’re inside a controller, then you can simply do:

$this->get('bugsnag')->notifyException(
    new Exception('Example exception!')
);

You can read more about service containers and dependency injection on the Symfony documentation.

Reporting unhandled exceptions

After completing installation and basic configuration, unhandled exceptions in your Symfony app will be automatically reported to your BugSnag dashboard.

Reporting handled 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.

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 and cookie 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:

$this->getBundle('bugsnag')->registerCallback(function ($report) {
    $report->setMetaData([
        'account' => [
            'name' => 'Acme Co.',
            'paying_customer' => true,
        ]
    ]);
});

For more information, see the customizing error reports reference.

In Symfony callbacks should be registered within the boot function of your app/AppKernel.php file:

public function boot()
{
    parent::boot();
    $this->getBundle('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. The last 25 breadcrumbs are attached to an error report to help diagnose what events lead to the error. Captured breadcrumbs are shown on your BugSnag dashboard as a part of the error report.

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.

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 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',
    ]);
});

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.

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.

Next steps