Customizing error reports

Add diagnostic data to every error report, conditionally adjust error reports, or indeed, skip notifying BugSnag of the error.

Adding callbacks

If you’d like to add diagnostic data to every error report, or adjust error reports conditionally, you can add callbacks which will be invoked each time a report will be sent.

$bugsnag->registerCallback(function ($report) {
    // For example, add customer information to every error report
    $report->setMetaData([
        'account' => [
            'name' => 'Acme Co.',
            'paying_customer' => true
        ]
    ]);
});

To cancel the error report, return false from the function.

See $report object for methods available within the callback.

The $report object

The following properties and methods are available on the $report object.

addMetaData

Add additional metadata to the error report, or delete existing metadata. Properties with a value of null will be deleted.

$report->addMetaData([
    'account' => [
        'paying' => true,
        'name' => 'Acme Co',
        'contact' => null # Will be deleted
    ]
]);

Conflicting properties will be merged recursively, favouring the newest values. For example:

$report->addMetaData([
    'account' => array(
        'id' => '0001',
        'name' => 'Acme Co'
    )
]);

$report->addMetaData([
    'account' => array(
        'name' => 'ACME'
    )
]);

Results in:

[
    'account' => [
        'id' => '0001',
        'name' => 'ACME'
    ]
]

getContext

Gets the current context of the report.

$context = $report->getContext();

getStacktrace

Gets the Stacktrace object attached to the error report, which contains the frames describing the series of calls leading to the error.

The Stacktrace object responds to the following methods:

The stacktrace is populated by frame arrays which have the following properties:

$stacktrace = $report->getStacktrace();
$frames = &$stacktrace->getFrames();

// Removes the top, `log_error` frame if present
if ($frames[0]['method'] == 'log_error') {
    $stacktrace->removeFrame(0);
}

// Sets `inProject` to `true` for anything with "vendor" in the path
foreach($frames as &$frame) {
    $inProject = substr_count($frame['file'], "vendor") > 0;
    $frame['inProject'] = $inProject;
}

getUser

Gets the associated user on the error.

$user = $report->getUser();

originalError

The error that caused the event in your application. This will be a Throwable if the error was caused by an exception, an array if the error was caused by a PHP error, such as a warning, or null if the error was reported with notifyError.

If the originalError is an array, it will have this structure:

$originalError = $report->getOriginalError();

setContext

Providing context for where the error occurred, context is given high visual prominence in the dashboard helping you to track specific issues quickly. This is typically set to a filename or request path automatically, depending on the framework and application type.

$report->setContext('myCustomContext');

setGroupingHash

Sets the grouping hash of the error report. All errors with the same grouping hash are grouped together. This is an advanced usage of the library and mis-using it will cause your errors not to group properly in your dashboard.

$report->setGroupingHash($report->getName() . $report->getMessage());

setMessage

Set the error message sent in the error report

$report->setMessage('This was a mistake.');

setMetaData

Set additional metadata to send with this error report, or replace existing metadata.

$report->setMetaData([
    'account' => array(
        'paying' => true,
        'name' => 'Acme Co'
    )
]);

If a conflict occurs while merging, the conflicting values will be placed into an array under the same key. For example:

$report->setMetaData([
    'account' => array(
        'id' => '0001',
        'name' => 'Acme Co'
    )
]);

$report->setMetaData([
    'account' => array(
        'name' => 'ACME'
    )
]);

Results in:

[
    'account' => [
        'id' => '0001',
        'name' => [
            'Acme Co',
            'ACME'
        ]
    ]
]

You can also pass a 2nd paramater of false stop us merging your metadata, and force us to completely replace it. For example:

$report->setMetaData([
    'account' => array(
        'id' => '0001',
        'name' => 'Acme Co'
    ),
    'diagnostics' => 'Failure'
]);

$report->setMetaData([
    'account' => array(
        'name' => 'ACME'
    )
], false);

Results in:

[
    'account' => [
        'name' => 'ACME'
    ]
]

setName

Set the error name sent in the error report

$report->setName('OopsError');

setSeverity

Set the severity of the error report. Valid severities are error, warning, and info.

By default, all unhandled exceptions are set to severity error and all handled exceptions are set to severity warning.

$report->setSeverity('info');

setUser

You can set the associated user on the error.

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