PHP

Introduction

PHPBrake is the official Airbrake PHP error notifier. PHPBrake supports PHP 5.4 and higher. PHPBrake includes many useful features that give you control over when and what you send to Airbrake.

Installation

composer require airbrake/phpbrake

Configuration

// Create new Notifier instance.
$notifier = new Airbrake\Notifier([
    'projectId' => 12345, // FIX ME
    'projectKey' => 'abcdefg' // FIX ME
]);

// Set global notifier instance.
Airbrake\Instance::set($notifier);

// Register error and exception handlers.
$handler = new Airbrake\ErrorHandler($notifier);
$handler->register();

// Somewhere in the app...
try {
    throw new Exception('hello from phpbrake');
} catch(Exception $e) {
    Airbrake\Instance::notify($e);
}

Setting severity

Severity allows categorizing how severe an error is. By default, it’s set to error. To redefine severity, simply overwrite context/severity of a notice object. For example:

$notice = $notifier->buildNotice($e);
$notice['context']['severity'] = 'critical';
$notifier->sendNotice($notice);

Error handler

Notifier can handle PHP errors, uncaught exceptions and shutdown. You can register appropriate handlers using following code:

$handler = new Airbrake\ErrorHandler($notifier);
$handler->register();

Under the hood $handler->register does following:

set_error_handler([$this, 'onError'], error_reporting());
set_exception_handler([$this, 'onException']);
register_shutdown_function([$this, 'onShutdown']);

appVersion

The version of your application that you can pass to differentiate exceptions between multiple versions. It’s not set by default.

$notifier = new Airbrake\Notifier([
    // ...
    'appVersion' => '1.2.3',
    // ...
]);

host

By default, it is set to api.airbrake.io. A host is a web address containing a scheme (“http” or “https”), a host and a port. You can omit the port (80 will be assumed) and the scheme (“https” will be assumed).

$notifier = new Airbrake\Notifier([
    // ...
    'host' => 'errbit.example.com', // put your errbit host here
    // ...
]);

remoteConfig

Configures the remote configuration feature. Every 10 minutes the notifier will make a GET request to Airbrake servers to fetching a JSON document containing configuration settings for your project. The notifier will apply these new settings at runtime. By default, it is enabled.

To disable this feature, configure your notifier with:

$notifier = new Airbrake\Notifier([
    // ...
    'remoteConfig' => false,
    // ...
]);

Note: it is not recommended to disable this feature. It might negatively impact how your notifier works. Please use this option with caution.

rootDirectory

Configures the root directory of your project. Expects a String or a Pathname, which represents the path to your project. Providing this option helps us to filter out repetitive data from backtrace frames and link to GitHub files from our dashboard.

$notifier = new Airbrake\Notifier([
    // ...
    'rootDirectory' => '/var/www/project',
    // ...
]);

environment

Configures the environment the application is running in. Helps the Airbrake dashboard to distinguish between exceptions occurring in different environments. By default, it’s not set.

$notifier = new Airbrake\Notifier([
    // ...
    'environment' => 'staging',
    // ...
]);

httpClient

Configures the underlying http client that must implement GuzzleHttp\ClientInterface.

// Supply your own client.
$client = new Airbrake\Http\GuzzleClient(
    new GuzzleHttp\Client(['timeout' => 3])
);

$notifier = new Airbrake\Notifier([
    // ...
    'httpClient' => $client,
    // ...
]);

Usage

Adding custom data to the notice

$notifier->addFilter(function ($notice) {
    $notice['context']['environment'] = 'production';
    return $notice;
});

Filtering sensitive data from the notice

$notifier->addFilter(function ($notice) {
    if (isset($notice['params']['password'])) {
        $notice['params']['password'] = 'FILTERED';
    }
    return $notice;
});

Ignoring specific exceptions

$notifier->addFilter(function ($notice) {
    if ($notice['errors'][0]['type'] == 'MyExceptionClass') {
        // Ignore this exception.
        return null;
    }
    return $notice;
});

Add user data to the notice

$notifier->addFilter(function ($notice) {
    $notice['context']['user']['name'] = 'Avocado Jones';
    $notice['context']['user']['email'] = 'AJones@guacamole.com';
    $notice['context']['user']['id'] = 12345;
    return $notice;
});

Filtering keys

With keysBlocklist option you can specify list of keys containing sensitive information that must be filtered out, e.g.:

$notifier = new Airbrake\Notifier([
    // ...
    'keysBlocklist' => ['/secret/i', '/password/i'],
    // ...
]);

Laravel integration

Please visit our Laravel docs for more info.

Symfony integration

Please visit airbrake-bundle for more info.

CakePHP 3.x integration

Please visit this gist for more info.

Zend Framework integration

Please visit zend-airbrake for more info.

Monolog integration

$log = new Monolog\Logger('billing');
$log->pushHandler(new Airbrake\MonologHandler($notifier));

$log->addError('charge failed', ['client_id' => 123]);