airbrake/phpbrake

Airbrake exception and error notifier for PHP

v0.4.1 2017-09-11 10:40 UTC

README

PHPBrake

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

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. Expects "guzzle", "curl", "default", or an instantiated client. If not set the default client is used.

  • In order to use the "guzzle" client, the composer package "guzzlehttp/guzzle" must be installed.
  • Curl needs the curl php extension installed. See phpinfo().
  • The default client uses the php function "file_get_contents". Make sure "allow_url_fopen" is set to "1" in your php.ini.
  • To provide your own client, instantiate and configure one of the clients in Airbrake\Http.
// Use the Curl client.
$notifier = new Airbrake\Notifier([
    // ...
    'httpClient' => 'curl',
    // ...
]);
// Supply your own client.
$client = new Airbrake\Http\GuzzleClient(
    new GuzzleHttp\Client(['timeout' => 3])
);

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

Running tests

composer install
vendor/bin/phpunit

PHPDoc

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

License

PHPBrake is licensed under The MIT License (MIT).