Bugsnag Notifier for PHP

The Bugsnag Notifier for PHP gives you instant notification of errors and exceptions in your PHP applications.

Bugsnag captures errors in real-time from your web, mobile and desktop applications, helping you to understand and resolve them as fast as possible. Create a free account to start capturing errors from your applications.

The Bugsnag Notifier for PHP supports PHP 5.2+.

How to Install

Using Composer (Recommended)

Install the bugsnag/bugsnag-php package:

$ composer require "bugsnag/bugsnag:2.*"

Using Phar Package

Download the latest bugsnag.phar to your PHP project.
Require it in your app.
```
require_once "/path/to/bugsnag.phar";
```

Manual Installation

Download and extract the latest Bugsnag source code to your PHP project.
Require it in your app using the provided autoloader.
```
require_once "/path/to/Bugsnag/Autoload.php";
```

Configuration

Configure Bugsnag with your API key:

$bugsnag = new Bugsnag_Client('YOUR-API-KEY-HERE');

Enable automatic error and exception notification by attaching Bugsnag's error and exception handlers:
```
set_error_handler(array($bugsnag, 'errorHandler'));
set_exception_handler(array($bugsnag, 'exceptionHandler'));
```
If you app or PHP framework already has error handling functions, you can also call $bugsnag->errorHandler and $bugsnag->exceptionHandler directly from your existing functions, simply pass all parameters through.

Sending Custom Data With Exceptions

It is often useful to send additional meta-data about your app, such as information about the currently logged in user, along with any error or exceptions, to help debug problems.

Bugsnag supports sending user information, such as the user's name or email address, by calling the setUser function.

To send other custom data, you should define a before-notify function, adding an array of "tabs" of custom data to the $metaData parameter. For an example, see the setBeforeNotifyFunction documentation below.

Sending Custom Errors or Non-Fatal Exceptions

You can easily tell Bugsnag about non-fatal or caught exceptions by calling notifyException:

$bugsnag->notifyException(new Exception('Something bad happened'));

You can also send custom errors to Bugsnag with notifyError:

$bugsnag->notifyError('ErrorType', 'Something bad happened here too');

Both of these functions can also be passed an optional $metaData parameter, which should take the following format:

$metaData =  array(
    'account' => array(
        'paying' => true,
        'name' => 'Acme Co'
    )
);

Severity

You can set the severity of an error in Bugsnag by including the severity option as the fourth parameter when notifying bugsnag of the error,

$bugsnag->notifyError('ErrorType', 'Something bad happened here too', NULL, "error")

Valid severities are error, warning and info.

Severity is displayed in the dashboard and can be used to filter the error list. By default all crashes (or unhandled exceptions) are set to error and all $bugsnag->notify calls default to warning.

Additional Configuration

###setUser

Bugsnag helps you understand how many of your users are affected by each error, and allows you to search for which errors affect a particular user using your Bugsnag dashboard. To send useful user-specific information you can call setUser:

$bugsnag->setUser(array(
    'name' => 'Leeroy Jenkins',
    'email' => 'leeeeroy@jenkins.com'
));

The name, email and id fields are searchable, and everything you send in this array will be displayed on your Bugsnag dashboard.

The id field is used also used by Bugsnag to determine the number of impacted users. By default, we use the IP address of the request as the id.

###setReleaseStage

If you would like to distinguish between errors that happen in different stages of the application release process (development, production, etc) you can set the releaseStage that is reported to Bugsnag.

$bugsnag->setReleaseStage('development');

By default this is set to "production".

###setNotifyReleaseStages

By default, we will notify Bugsnag of errors that happen in any releaseStage If you would like to change which release stages notify Bugsnag of errors you can call setNotifyReleaseStages:

$bugsnag->setNotifyReleaseStages(array('development', 'production'));

###setMetaData

Sets additional meta-data to send with every bugsnag notification, for example:

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

###setContext

Bugsnag uses the concept of "contexts" to help display and group your errors. Contexts represent what was happening in your application at the time an error occurs. By default this will be set to the current request URL and HTTP method, eg "GET /pages/documentation".

If you would like to set the bugsnag context manually, you can call setContext:

$bugsnag->setContext('Backport Job');

###setType

You can set the type of application executing the current code by using setType:

$bugsnag->setType('resque');

This is usually used to represent if you are running plain PHP code "php", via a framework, eg "laravel", or executing through delayed worker code, eg "resque". By default this is NULL.

###setFilters

Sets the strings to filter out from the metaData arrays before sending them to Bugsnag. Use this if you want to ensure you don't send sensitive data such as passwords, and credit card numbers to our servers. Any keys which contain these strings will be filtered.

$bugsnag->setFilters(array('password', 'credit_card'));

By default, this is set to be array("password").

###setEndpoint

Set the endpoint to send error reports to. By default we'll send reports to the standard https://notify.bugsnag.com endpoint, but you can override this if you are using Bugsnag Enterprise, to point to your own Bugsnag endpoint:

$bugsnag->setEndpoint("http://bugsnag.internal.example.com");

###setTimeout

Define a custom timeout in seconds for the connection when notifying bugsnag.com.

$bugsnag->setTimeout(2);

By default, this is set to be 2.

###setBeforeNotifyFunction

Set a custom function to call before notifying Bugsnag of an error. You can use this to call your own error handling functions, to add custom tabs of data to each error on your Bugsnag dashboard, or to modify the stacktrace.

To add custom tabs of meta-data, simply add to the $metaData array that is passed as the first parameter to your function, for example:

$bugsnag->setBeforeNotifyFunction('before_bugsnag_notify');

function before_bugsnag_notify(Bugsnag_Error $error) {
    // Do any custom error handling here

    // Also add some meta data to each error
    $error->setMetaData(array(
        "user" => array(
            "name" => "James",
            "email" => "james@example.com"
        )
    ));
}

If Bugsnag is called by a wrapper library, you can remove stack frames from the back-trace. For example:

function before_bugsnag_notify(Bugsnag_Error $error) {

    $firstFrame = $error->stacktrace->frames[0];
    if ($firstFrame && $firstFrame['file'] === 'My_Logger.php') {
        array_splice($error->stacktrace->frames, 0, 1);
    }

}

You can also return FALSE from your beforeNotifyFunction to stop this error from being sent to bugsnag.

###setAutoNotify

Controls whether bugsnag should automatically notify about any errors it detects in the PHP error handlers.

$bugsnag->setAutoNotify(FALSE);

By default, this is set to TRUE.

###setErrorReportingLevel

Set the levels of PHP errors to report to Bugsnag, by default we'll use the value of error_reporting from your php.ini or any value you set at runtime using the error_reporting(...) function.

If you'd like to send different levels of errors to Bugsnag, you can call setErrorReportingLevel:

$bugsnag->setErrorReportingLevel(E_ALL & ~E_NOTICE);

See PHP's error reporting documentation for allowed values.

###setProjectRoot

We mark stacktrace lines as in-project if they come from files inside your projectRoot. By default this value is automatically set to be $_SERVER['DOCUMENT_ROOT'] but sometimes this can cause problems with stacktrace highlighting. You can set this manually by calling setProjectRoot:

$bugsnag->setProjectRoot('/path/to/your/app');

If your app has files in many different locations, you should consider using setProjectRootRegex instead.

###setProjectRootRegex

If your app has files in many different locations, you can set the a regular expression for matching filenames in stacktrace lines that are part of your application:

$bugsnag->setProjectRootRegex('('.preg_quote('/app').'|'.preg_quote('/libs').')');

###setProxySettings

Note: Proxy configuration is only possible if the PHP cURL extension is installed.

If your server is behind a proxy server, you can configure this as well:

$bugsnag->setProxySettings(array(
    'host' => 'bugsnag.com',
    'port' => 42,
    'user' => 'username',
    'password' => 'password123'
));

Other than the host, none of these settings are mandatory.

###setAppVersion

If you tag your app releases with version numbers, Bugsnag can display these on your dashboard if you call setAppVersion:

$bugsnag->setAppVersion('1.2.3');

###setSendEnvironment

Bugsnag can transmit your $_ENV environment to help diagnose issues. This can contain private/sensitive information, so we do not transmit this by default. To send your environment, you can call setSendEnvironment:

$bugsnag->setSendEnvironment(true);

###setSendCode

Bugsnag automatically sends a small snippet of the code that crashed to help you diagnose even faster from within your dashboard. If you don't want to send this snippet, you can call setSendCode:

$bugsnag->setSendCode(false);

###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.

$error->setGroupingHash($exception->message . $exception->class);

PHP Frameworks

Laravel

Check out the bugsnag-laravel plugin.

WordPress

Check out the WordPress Error Monitoring by Bugsnag plugin.

CakePHP

Check out the third-party Label305/bugsnag-cakephp plugin.

Magento

Check out the official Bugsnag Magento Extension.

Symfony2

Check out the third-party evolution7/Evolution7BugsnagBundle or wrep/bugsnag-php-symfony bundles.

Monolog

Check out the 3rd party log handler for monolog: meadsteve/MonoSnag/

Silverstripe

Check out the third-party evolution7/silverstripe-bugsnag-logger plugin.

Zend Framework 2

Check out the third-party nickurt/bugsnag-php plugin.

Building a Phar from Source

Install the composer dependencies
```
$ composer install
```
Build the phar using pharbuilder.php. You may need to set phar.readonly = Off in your php.ini.
```
php pharbuilder.php
```

A new bugsnag.phar will be generated in the build folder.

Reporting Bugs or Feature Requests

Please report any bugs or feature requests on the github issues page for this project here:

https://github.com/bugsnag/bugsnag-php/issues

Contributing

Fork the notifier on github
Commit and push until you are happy with your contribution
Run the tests to make sure they all pass: composer install && vendor/bin/phpunit
Make a pull request
Thanks!

License

The Bugsnag PHP notifier is free software released under the MIT License. See LICENSE.txt for details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Bugsnag Notifier for PHP

How to Install

Using Composer (Recommended)

Using Phar Package

Manual Installation

Configuration

Sending Custom Data With Exceptions

Sending Custom Errors or Non-Fatal Exceptions

Severity

Additional Configuration

PHP Frameworks

Laravel

WordPress

CakePHP

Magento

Symfony2

Monolog

Silverstripe

Zend Framework 2

Building a Phar from Source

Reporting Bugs or Feature Requests

Contributing

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

Bugsnag Notifier for PHP

How to Install

Using Composer (Recommended)

Using Phar Package

Manual Installation

Configuration

Sending Custom Data With Exceptions

Sending Custom Errors or Non-Fatal Exceptions

Severity

Additional Configuration

PHP Frameworks

Laravel

WordPress

CakePHP

Magento

Symfony2

Monolog

Silverstripe

Zend Framework 2

Building a Phar from Source

Reporting Bugs or Feature Requests

Contributing

License