Php Airbrake Bundle Laravel Package

Getting Started

• Reality check first: this is a Symfony2 bundle, not a Laravel package. There is no service provider, no facade, and composer require nodrew/php-airbrake-bundle will drag in symfony/framework-bundle and its version constraints. In a Laravel app you cannot install it as-is; the practical move is to read it as a blueprint and reproduce the two things it does: configure an Airbrake client and hook exception reporting.
• Where to look first:
  • composer.json — PHP floor (likely 5.3.x), Symfony constraint, and the underlying notifier (nodrew/php-airbrake / dbtlr/php-airbrake). This tells you whether anything is salvageable.
  • DependencyInjection/Configuration.php — the real config surface: api_key, environment, queue, timeout, excluded exceptions.
  • Resources/config/services.yml — the service IDs (typically airbrake.client, airbrake.exception_listener) and how they're constructed.
  • The exception listener / event subscriber — what metadata (component, action, route) it attaches to a notice.
• First use case to replicate: capture uncaught exceptions from the framework's central exception hook and post one Airbrake notice per error, tagged with environment and component. In Symfony that is kernel.exception; in Laravel the equivalent single insertion point is App\Exceptions\Handler::report().

Minimal Laravel-side steps to get the same behavior:

1. composer require nodrew/php-airbrake if a compatible version resolves — otherwise use a maintained notifier, since only the client matters here.
2. Bind a configured client as a singleton in a service provider.
3. Report from the exception handler, not from middleware or a controller.

Implementation Patterns

• Client as a singleton. The bundle registers a configured Airbrake\Client in the container. Mirror that in Laravel:

$this->app->singleton(\Airbrake\Client::class, fn () => new \Airbrake\Client(
    new \Airbrake\Configuration(config('airbrake.api_key'), [
        'environmentName' => app()->environment(),
        'component'       => 'laravel',
        'timeout'         => 2,
    ])
));

• Exception reporting through the handler. This is the day-to-day integration point; keep it guarded and cheap:

public function report(Throwable $e): void
{
    if (! config('app.debug') && $this->shouldReport($e)) {
        try {
            app(\Airbrake\Client::class)->notifyOnException($e);
        } catch (Throwable $ignored) {
            // never let the notifier mask the original error
        }
    }

    parent::report($e);
}

• $dontReport is the Laravel analog of the bundle's excluded-exception list. Keep 404s, ValidationException, and auth failures out of Airbrake — this single list does more for signal quality than any other setting.
• Monolog handler pattern. If the bundle ships an Airbrake Monolog handler, the Laravel equivalent is a dedicated logging channel or a tap class on the logger that forwards only >= warning, so logged-but-handled errors still reach Airbrake.
• Context enrichment. Symfony bundles usually attach component, action (route), and request info. In Laravel, attach the route name and authenticated user ID to the notice so errors group sensibly in the dashboard instead of producing one bucket per closure.
• Environment gating. The bundle lets you toggle per environment; replicate with config/airbrake.php reading APP_ENV, and disable entirely for local and testing so test runs never hit the network.
• Stay out of middleware. Converting the kernel listener to HTTP middleware misses exceptions thrown during bootstrap and inside the handler itself. The exception handler is the only place with full coverage.
• Defer the HTTP call if latency matters. Old Airbrake clients post synchronously over cURL. On slow error paths, dispatch a queued job with the serialized exception rather than blocking the request.

Gotchas and Tips

• DI schema mismatch. Symfony2-era bundles use services.yml with the old schema and @service references; they won't autoload as PSR-4. Even if Composer resolves, the bundle's container wiring is inert in Laravel.
• API version drift is the biggest functional risk. Airbrake moved from v2 XML notices (/notifier_api/v2/notices) to v3/v4 endpoints with project keys and different payload shapes. Check what endpoint the bundled client targets and test a manual notify() before trusting the listener — a wrong key or endpoint often fails silently with a 4xx.
• Recursion and hangs. If a transport failure is itself reported back into the notifier, you can loop or stall the response. Set a short timeout, catch transport exceptions in report(), and never let Airbrake throw into the error path.
• Ordering matters. In Symfony, listener priority determines whether you see the original or a wrapped exception. In Laravel, report() runs before rendering — throwing there replaces the user-facing error with a 500 and destroys the original stack trace.
• Dashboard filters are a common "it's broken." If nothing shows up, first confirm the environment name on the notice matches the filter in Airbrake. Dump getConfiguration() and the serialized notice to verify what is actually being sent.
• Backtrace quality. Old php-airbrake versions let you tune backtrace options; the defaults can omit application frames. Configure them so the top of the trace points at your code, not vendor internals.
• Extension points. In the bundle you'd swap the airbrake.client service or subclass the exception listener. In Laravel, bind an interface and decorate it, or add a reportable() callback for one-off exceptions needing extra params — that's the cleanest seam for customizing payloads.
• Bus factor. Fourteen stars and zero dependents means no community safety net and no security triage. Treat this repository as a reference implementation for wiring an Airbrake notifier into a framework, not as a dependency you want to carry in a Laravel codebase.