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.

Supported Frameworks#

Phpbrake provides a ready-to-use solution with minimal configuration for php frameworks.

Laravel

Magento

Wordpress

Installation & Configuration#

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'] = '[email protected]';
    $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]);