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

1. Install the bugsnag/bugsnag-php package:

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

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

2. Require it in your app.

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

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";

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.

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.

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

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.

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

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

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

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

Check out the bugsnag-laravel plugin.

Check out the WordPress Error Monitoring by Bugsnag plugin.

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

Check out the official Bugsnag Magento Extension.

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

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

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

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

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

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

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

• 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!

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