README

PHPBrake

Features

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

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'] = 'AJones@guacamole.com';
    $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
    // ...
]);

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

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

Running tests

Run via docker:

docker compose run tests

Or run locally

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:

License

PHPBrake is licensed under The MIT License (MIT).

airbrake / phpbrake

Maintainers

Details