Other PHP apps

Add BugSnag to other PHP applications, such as standalone scripts.

This library supports PHP 5.5+, to integrate BugSnag with older PHP versions (5.2+), check out our legacy integration.

Installation

Using Composer

Add bugsnag/bugsnagto your composer.json as follows:

$ composer require "bugsnag/bugsnag:^3.0"

Using a phar package

Download guzzle.phar from the latest v6 release of Guzzle.

Download bugsnag.phar from the latest release of bugsnag-php.

Require guzzle and bugsnag in your application:

require_once "/path/to/guzzle.phar";
require_once "/path/to/bugsnag.phar";

Basic configuration

Create a BugSnag client object with your Integration API Key:

$bugsnag = Bugsnag\Client::make('YOUR-API-KEY-HERE');

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

On-premise users can set their endpoint by passing a 2nd parameter to this function:

$bugsnag = Bugsnag\Client::make('YOUR-API-KEY-HERE', 'https://your-endpoint.com/');

We also support reading your information from environment variables. If you have BUGSNAG_API_KEY (and optionally BUGSNAG_ENDPOINT) set, we will simply read those values, enabling you to build our client without passing any parameters:

$bugsnag = Bugsnag\Client::make();

If you’d like to configure BugSnag further, check out the configuration options reference.

Reporting unhandled exceptions

You can ensure that all unhandled errors and exceptions are reported to BugSnag by registering our exception handler as follows:

Bugsnag\Handler::register($bugsnag);

This will also call existing exception handlers. At this point, BugSnag should be installed and configured, and any unhandled exceptions will be automatically detected and should appear in your BugSnag dashboard.

Reporting out of memory exceptions

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 reporting unhandled exceptions steps. To disable this, or change the amount of extra memory BugSnag allocates, see the memory limit increase configuration option.

Reporting handled exceptions

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.

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:

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

For more information, see the customizing error reports reference.

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.

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.

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.

You can set this information as follows:

$bugsnag->registerCallback(function ($report) {
    $report->setUser([
        'id' => '123456',
        'name' => 'Leeroy Jenkins',
        'email' => 'leeeeroy@jenkins.com',
    ]);
});

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.

Sessions can be created manually by calling startSession on the BugSnag client:

$bugsnag->startSession()

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.

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 by calling $bugsnag->build() or you can call our Build API directly.

For more information, see our PHP Build Integrations guide.

Next steps

• Catch and report errors in your client-side JavaScript with the Browser error monitoring guide
• Monitor the performance of your web app in your users’ browsers with the Web performance guide
• View bugsnag-php, the open-source library powering BugSnag for PHP, on GitHub
• Get support for your questions and feature requests