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+ and requires the cURL PHP extension to be available.

How to Install

Using Composer (Recommended)

1. Install the bugsnag/bugsnag-php package:

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

Using Phar Package

1. Download the latest bugsnag.phar to your PHP project.

2. Require it in your app.

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

Manual Installation

1. Download and extract the latest Bugsnag source code to your PHP project.

2. Require it in your app using the provided autoloader.

   require_once "/path/to/Bugsnag/Autoload.php";

Configuration

1. Configure Bugsnag with your API key:

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

2. 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'
    )
);

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 be "production".

Note: If you would like errors from stages other than production to be sent to Bugsnag, you'll also have to call setNotifyReleaseStages.

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

###setUseSSL

Enforces all communication with bugsnag.com be made via ssl.

$bugsnag->setUseSSL(TRUE);

By default, this is set to be TRUE.

###setTimeout

Define a custom timeout, in seconds, for cURL 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, or to add custom tabs of data to each error on your Bugsnag dashboard.

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($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"
        )
    ));
}

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

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');

PHP Frameworks

Laravel

Check out the bugsnag-laravel plugin.

WordPress

Check out the WordPress Error Monitoring by Bugsnag plugin.

CakePHP

If you are using CakePHP, installation is easy:

1. Follow the Bugsnag installation instructions above

2. Edit App/Config/core.php:

   // Require Bugsnag
   require_once("path/to/bugsnag.php");
   
   // Initialize Bugsnag
   $bugsnag->register("YOUR-API-KEY-HERE");
   
   // Change the default error handler to be Bugsnag
   Configure::write('Error', array(
       'handler' => array($bugsnag, 'errorHandler'),
       'level' => E_ALL & ~E_DEPRECATED,
       'trace' => true
   ));
   
   // Change the default exception handler to be Bugsnag
   Configure::write('Exception', array(
       'handler' => array($bugsnag, 'exceptionHandler'),
       'renderer' => 'ExceptionRenderer',
       'log' => true
   ));

Symfony2

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

Silverstripe

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

Building a Phar from Source

• Install the composer dependencies

  $ composer install

• Build the phar using box

  $ vendor/bin/box build

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.