The official Airbrake PHP error notifier
Clone or download
Latest commit 84dd7cf Jul 5, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Update docs Jul 5, 2018
tests Add keysBlacklist option Jul 5, 2018
.gitattributes Add gitattributes for smaller download size Aug 28, 2015
.gitignore Rename phpunit.xml to phpunit.xml.dist Aug 27, 2015
.travis.yml Use vendored phpunit Jun 13, 2017
CHANGELOG.md Fix changelog Sep 7, 2017
LICENSE Add license Aug 28, 2015
README.md Update docs Jul 5, 2018
composer.json Add code hunks support Oct 30, 2017
phpunit.xml.dist Rename phpunit.xml to phpunit.xml.dist Aug 27, 2015

README.md

PHPBrake Build Status

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

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

License

PHPBrake is licensed under The MIT License (MIT).