PHPBrake

Features

PHPBrake is the official Airbrake PHP error notifier. PHPBrake includes many useful features that give you control over when and what you send to Airbrake, you can:

• Send notices from try-catch blocks in your code
• Add custom data to a notice
• Filter sensitive data from the notice
• Ignore specific exceptions
• Configure an error handler to capture uncaught exceptions
• Integrate with monolog
• Integrate with Laravel
• Integrate with CakePHP 3.x
• Integrate with Symfony
• Integrate with Zend
• and more

Installation

composer require airbrake/phpbrake

Quickstart

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

API

Notifier API consists of 4 methods:

• buildNotice - builds Airbrake notice.
• sendNotice - sends notice to Airbrake.
• notify - shortcut for buildNotice and sendNotice.
• addFilter - adds filter that can modify and/or filter notices.

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'] = '[email protected]';
    $notice['context']['user']['id'] = 12345;
    return $notice;
});

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

Laravel integration

See https://github.com/TheoKouzelis/laravel-airbrake

Symfony integration

See https://github.com/aminin/airbrake-bundle

CakePHP 3.x integration

See https://gist.github.com/mauriciovillalobos/01a97f9ee6179ad70b17d54f37cc5010

Zend Framework integration

See https://github.com/FrankHouweling/zend-airbrake

Monolog integration

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

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

Extra configuration options

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
    // ...
]);

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,
    // ...
]);

Filtering keys

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

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

Running tests

composer install
vendor/bin/phpunit

PHPDoc

composer require phpdocumentor/phpdocumentor
vendor/bin/phpdoc -d src
firefox output/index.html

Contact

In case you have a problem, question or a bug report, feel free to:

• file an issue
• send us an email

License

PHPBrake is licensed under The MIT License (MIT).