Getting Started

Assessment up front: dbtlr/php-airbrake is explicitly deprecated by its author, who recommends the official airbrake/phpbrake package instead. It is not Laravel-aware, has no service provider or facade, and has had no release since June 2018. For a new Laravel project, do not adopt it. Use it only to maintain or extract an existing integration, then migrate to the official package.

If you inherit a codebase using it:

composer require dbtlr/php-airbrake

Confirm what Composer actually installed and whether it is compatible with your PHP runtime:

composer show dbtlr/php-airbrake
php -v

Minimal bootstrap:

use Airbrake\Client;
use Airbrake\Configuration;

$config = new Configuration(config('services.airbrake.key'), [
    'environmentName' => app()->environment(),
    'projectId'       => config('services.airbrake.project_id'),
    'appVersion'      => config('app.version'),
    'secure'          => true,
]);

$client = new Client($config);
$client->notifyOnException($e);

Where to look first in vendor/dbtlr/php-airbrake:

src/Airbrake/Configuration.php — all supported options and defaults.
src/Airbrake/Client.php — notifyOnException() and any custom-notice entry point.
src/Airbrake/Filter/ — how notice payloads can be scrubbed before sending.
The README examples — sparse, but they show the intended configuration shape.

First practical use case: wire it into Laravel's exception handler so uncaught exceptions in HTTP requests, queue workers, and console commands are reported with environment and version metadata.

Implementation Patterns

1. Keep credentials in config/services.php and .env.

// config/services.php
'airbrake' => [
    'key'        => env('AIRBRAKE_KEY'),
    'project_id' => env('AIRBRAKE_PROJECT_ID'),
],

AIRBRAKE_KEY=your-api-key
AIRBRAKE_PROJECT_ID=your-project-id

2. Bind a singleton in a service provider.

// app/Providers/AppServiceProvider.php
use Airbrake\Client;
use Airbrake\Configuration;

public function register()
{
    $this->app->singleton('airbrake.client', function ($app) {
        $config = new Configuration(config('services.airbrake.key'), [
            'environmentName' => $app->environment(),
            'projectId'       => config('services.airbrake.project_id'),
            'appVersion'      => config('app.version'),
            'secure'          => true,
        ]);

        return new Client($config);
    });
}

3. Hook into Laravel's exception handler.

// app/Exceptions/Handler.php
public function report(Throwable $e)
{
    if ($this->shouldReport($e) && app()->bound('airbrake.client')) {
        $client = app('airbrake.client');

        // The library is PHP 5.3-era and may type-hint \Exception.
        // Wrap PHP 7+ Errors if the signature rejects Throwable.
        if ($e instanceof \Exception) {
            $client->notifyOnException($e);
        } else {
            $client->notifyOnException(
                new \ErrorException($e->getMessage(), 0, E_ERROR, $e->getFile(), $e->getLine(), $e)
            );
        }
    }

    parent::report($e);
}

4. Report caught exceptions deliberately. Don't report everything; use it for exceptions that indicate a real operational problem, not expected validation failures:

try {
    $this->chargeCustomer($order);
} catch (\PaymentGatewayException $e) {
    app('airbrake.client')->notifyOnException($e);
    throw $e;
}

5. Scrub sensitive data with filters. Exceptions often contain request parameters, tokens, and PII in messages or context. Implement the package's filter interface (check its exact signature in vendor/) and register it on the configuration before constructing the client:

$config->addFilter(new class implements \Airbrake\Filter\FilterInterface {
    public function filter(array $notice)
    {
        $notice['error_message'] = preg_replace(
            '/(password|token|secret)=[^&\s]+/i',
            '$1=[FILTERED]',
            $notice['error_message']
        );

        return $notice;
    }
});

6. Use it in non-HTTP contexts. Laravel's handler covers queue jobs and Artisan commands, but long-running workers can hold stale client state. Make sure the singleton does not cache request-specific data across jobs/requests.

7. Add an explicit test path. In local and testing environments, either skip notification entirely or point to a non-production key:

if (app()->environment('production', 'staging') && config('services.airbrake.key')) {
    // notify
}

8. Consider async delivery only if the package version supports it. The package has historically offered an async/queue mechanism. Check the Configuration options in your installed version. In Laravel, a safer pattern is to dispatch exception reporting through a queued job, keeping the user request fast.

Gotchas and Tips

The package is abandoned. The author states he no longer maintains it and recommends airbrake/phpbrake. Treat any new work as migration work. Audit it before relying on it for production alerting.
PHP 8 compatibility is unlikely to be clean. This is PHP 5.3-era code. Expect deprecation warnings, dynamic-property issues, and type-signature problems on modern PHP. Test on your exact runtime before wiring into Handler::report().
notifyOnException() may type-hint \Exception. In PHP 7+, Error and TypeError are Throwable but not Exception. Passing them directly can produce a TypeError. Wrap or convert as shown above.
Airbrake's API and account model changed. Older Airbrake setups used only an API key; newer projects require a project ID and different endpoints. If notices silently fail, check projectId, secure, and the host/endpoint in Configuration. Verify against your Airbrake project settings, not just the README.
No Laravel auto-discovery. You must register the binding and call the client yourself. There is no facade, no config publishing, and no documented Laravel integration.
Avoid double reporting. If you register a global PHP error/exception handler and also report from Laravel's handler, the same error can produce duplicate notices. Let Laravel's handler be the single entry point.
Network failures must not break the request. Error reporting is an outbound HTTP call. If it throws or hangs, you can turn a minor error into a 500. Check whether the version supports timeouts, and consider wrapping notification in a try/catch that logs locally.
Filter before sending, not after. Exception messages, stack traces, and extra context can leak passwords, tokens, and PII. Verify the filter chain is actually invoked; inspect the outgoing payload in a staging environment with a test exception.
Check vendor/ rather than assuming API compatibility. The README is incomplete and the API changed over the package's lifetime. The installed source is the authoritative reference for method names, option keys, and filter signatures.
Version-pin and isolate. Use an exact or tight constraint in composer.json, and avoid letting this dependency leak into shared libraries. When migrating to airbrake/phpbrake, centralize the client creation in one binding so only that file needs to change.
Migration path: replace the dbtlr/php-airbrake binding with airbrake/phpbrake, keep the same notifyOnException() call site in Handler::report(), and move filters to the new package's filter API. Doing this behind a small internal interface (e.g. ExceptionReporter) makes the migration and future swaps trivial.

Php Airbrake Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips