README

A native CakePHP 5.x plugin for Airbrake error tracking and exception monitoring. Automatically captures and reports exceptions, PHP errors, and log messages to Airbrake using API v3. This plugin does not depend on the legacy phpairbrake SDK.

No external dependencies - uses CakePHP's built-in HTTP client.

Features

Native implementation using Airbrake API v3
No phpairbrake SDK dependency
Automatic exception and error tracking
Seamless integration with CakePHP's error handling system
Log engine for sending log messages to Airbrake
Request context (URL, HTTP method, route, user agent, etc.)
CakePHP route information (controller, action, prefix)
User identification support (CakePHP Authentication plugin)
Sensitive data filtering (passwords, tokens, etc.)
Support for self-hosted Airbrake (Errbit)
Environment-based configuration
Zero external dependencies

Requirements

PHP 8.1 or higher
CakePHP 5.x
Airbrake account (or self-hosted Errbit)

Installation

Install the plugin using Composer:

composer require salines/cakephp-airbrake

Migration from phpairbrake

If your application previously used the phpairbrake SDK, you can remove it from composer.json and keep the same Airbrake credentials. This plugin provides its own notifier (Airbrake\Notifier) and sends notices directly using CakePHP's HTTP client.

Configuration

1. Load the Plugin

Add the plugin to your src/Application.php:

public function bootstrap(): void
{
    parent::bootstrap();

    $this->addPlugin('Airbrake');
}

Or use the CLI:

bin/cake plugin load Airbrake

2. Configure Airbrake

Add the Airbrake configuration to your config/app.php:

'Airbrake' => [
    'projectId' => env('AIRBRAKE_PROJECT_ID'),
    'projectKey' => env('AIRBRAKE_PROJECT_KEY'),
    'environment' => env('APP_ENV', 'production'),
    'appVersion' => '1.0.0',
    'host' => 'https://api.airbrake.io', // Change for self-hosted
    'enabled' => true,
    'rootDirectory' => ROOT,
    'keysBlocklist' => [
        '/password/i',
        '/secret/i',
        '/token/i',
        '/authorization/i',
        '/api_key/i',
    ],
],

3. Configure Error Logger

To automatically send all exceptions and errors to Airbrake, configure the error logger in config/app.php:

'Error' => [
    'errorLevel' => E_ALL,
    'exceptionRenderer' => \Cake\Error\Renderer\WebExceptionRenderer::class,
    'skipLog' => [],
    'log' => true,
    'trace' => true,
    'logger' => \Airbrake\Error\AirbrakeErrorLogger::class,
],

4. Configure Log Engine (Optional)

To send log messages to Airbrake, add the log engine configuration:

'Log' => [
    'airbrake' => [
        'className' => 'Airbrake.Airbrake',
        'levels' => ['warning', 'error', 'critical', 'alert', 'emergency'],
    ],
],

The log engine automatically uses the global Airbrake configuration.

Environment Variables

You can configure the plugin using environment variables:

AIRBRAKE_PROJECT_ID=123456
AIRBRAKE_PROJECT_KEY=your-project-key
AIRBRAKE_HOST=https://api.airbrake.io
AIRBRAKE_ENABLED=true
APP_ENV=production

Usage

Automatic Error Tracking

Once configured with the error logger, all uncaught exceptions and PHP errors will automatically be sent to Airbrake.

Manual Exception Reporting

You can manually send exceptions to Airbrake:

use Airbrake\Notifier;
use Cake\Core\Configure;

try {
    // Your code
} catch (\Exception $e) {
    $notifier = new Notifier(Configure::read('Airbrake'));
    $notifier->notify($e);
}

Using the Log Engine

Send log messages to Airbrake:

use Cake\Log\Log;

Log::error('Something went wrong', ['scope' => 'airbrake']);
Log::critical('Database connection failed');

// With exception context
Log::error('Operation failed', [
    'exception' => $e,
    'user_id' => 123,
]);

Adding Custom Context

You can add custom context to your error reports using filters:

use Airbrake\Notifier;
use Cake\Core\Configure;

$notifier = new Notifier(Configure::read('Airbrake'));

$notifier->addFilter(function ($notice) {
    $notice['context']['customField'] = 'customValue';
    $notice['params']['orderId'] = 12345;
    return $notice;
});

$notifier->notify($exception);

Filtering Notices

You can prevent certain notices from being sent by returning null from a filter:

$notifier->addFilter(function ($notice) {
    // Don't send 404 errors
    if (str_contains($notice['errors'][0]['type'], 'NotFoundException')) {
        return null;
    }
    return $notice;
});

Setting Severity

You can set the severity level for notices:

$notifier = new Notifier(Configure::read('Airbrake'));
$notice = $notifier->buildNotice($exception);
$notice['context']['severity'] = 'critical'; // debug, info, notice, warning, error, critical
$notifier->sendNotice($notice);

Testing With webhook.site

You can test delivery without a real Airbrake project by sending notices to a webhook.site URL.

Create a new endpoint at https://webhook.site and copy the unique URL.
Configure a custom notices URL:

'Airbrake' => [
    'projectId' => 1,
    'projectKey' => 'test-key',
    'customNoticesUrl' => 'https://webhook.site/your-unique-id',
],

Trigger a test notice:

use Airbrake\Notifier;
use Cake\Core\Configure;

$notifier = new Notifier(Configure::read('Airbrake'));
$notifier->notify(new \RuntimeException('Webhook test notice'));

Open the webhook.site page to inspect the JSON payload.

Configuration Options

Option	Type	Default	Description
`projectId`	int	null	Your Airbrake project ID (required)
`projectKey`	string	null	Your Airbrake project key (required)
`environment`	string	'production'	Environment name
`appVersion`	string	null	Application version
`host`	string	'https://api.airbrake.io'	Airbrake API host
`enabled`	bool	true	Enable/disable Airbrake reporting
`keysBlocklist`	array	[...]	Regex patterns for sensitive keys to filter
`rootDirectory`	string	ROOT	Root directory for backtrace filtering
`httpClientOptions`	array	['timeout' => 10]	Options for CakePHP HTTP Client

Self-Hosted Airbrake (Errbit)

To use with a self-hosted Airbrake server like Errbit:

'Airbrake' => [
    'projectId' => 1,
    'projectKey' => 'your-api-key',
    'host' => 'https://your-errbit-server.com',
    // ... other options
],

Filtering Sensitive Data

The plugin automatically filters sensitive data based on the keysBlocklist configuration. By default, it filters keys matching:

/password/i
/secret/i
/token/i
/authorization/i
/api_key/i
/apikey/i
/access_token/i

You can add your own patterns:

'keysBlocklist' => [
    '/password/i',
    '/secret/i',
    '/credit_card/i',
    '/ssn/i',
    '/cvv/i',
],

Disabling in Development

You can disable Airbrake in development:

'Airbrake' => [
    // ... other config
    'enabled' => !Configure::read('debug'),
],

Or using environment variables:

AIRBRAKE_ENABLED=false

Notice Structure

The plugin sends notices to Airbrake in the following structure (API v3):

{
  "errors": [{
    "type": "RuntimeException",
    "message": "Something went wrong",
    "backtrace": [...]
  }],
  "context": {
    "notifier": {"name": "cakephp-airbrake", "version": "1.0.0"},
    "environment": "production",
    "hostname": "server-01",
    "os": "Linux",
    "language": "PHP 8.1.0",
    "severity": "error",
    "url": "https://example.com/users/123",
    "httpMethod": "GET",
    "route": "/Users/view",
    "component": "Users",
    "action": "view",
    "user": {"id": 1, "name": "John", "email": "john@example.com"}
  },
  "environment": {...},
  "params": {...},
  "session": {...}
}

Testing

Run the tests:

composer install
./vendor/bin/phpunit

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Airbrake - Error monitoring service
CakePHP - PHP framework

salines / cakephp-airbrake

Maintainers

Details