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:

method description
getFrames() Returns an Array of frames
addFrame($file, $line, $method, $class=null) Creates a new frame in the stacktrace, adding it to the end of the frames array
removeFrame($index) Removes a frame at the given index

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

property type description
lineNumber int The line number the frame occurred on
method string The called method and, if available, the parent class
code array An array of code lines surrounding the called method if sending code is enabled
inProject bool Whether the frame occurred inside the project codebase. This is predetermined based on the frame’s file path and your configured project root, but can be set manually to improve grouping and stacktrace readability
file string The file the frame occurred in, with the path stripped as described here
$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:

key description
code An integer error code, as described in the PHP manual
message The error message
file The file path where the error occurred
line The line number where the error occurred
fatal A boolean indicating if this was a fatal error

Manipulating originalError does not affect the error information reported to the BugSnag dashboard.

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