Airbrake Bundle Laravel Package

Getting Started

Reality check before anything else: this is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no package auto-discovery, no config/airbrake.php, and composer require incompass/airbrake-bundle in a Laravel app installs a bundle that Laravel's container will never boot. If you are on Laravel, stop and wire airbrake/airbrake-php yourself via a thin service provider bound to Exceptions\Handler::report(). The rest of this assessment assumes you have been dropped into a Symfony 2/3/4 codebase and need error reporting working today.

Minimal path to first report:

1. composer require incompass/airbrake-bundle. Pin the version explicitly — with zero dependents and effectively no release cadence, treat every bump as breaking until proven otherwise.

2. Register the bundle. Symfony 2/3: append new Incompass\AirbrakeBundle\AirbrakeBundle() in AppKernel::registerBundles(). Symfony 4+: add it to config/bundles.php.

3. Read DependencyInjection/Configuration.php first. The config tree — not the README — is the only trustworthy source of the root key, required fields, and defaults. Expect a shape close to:

   # config/packages/airbrake.yaml
   incompass_airbrake:
       api_key:     "%env(AIRBRAKE_API_KEY)%"
       project_id:  "%env(AIRBRAKE_PROJECT_ID)%"
       environment: "%kernel.environment%"
       host:        "https://api.airbrake.io"
   

4. Open Resources/config/services.yml to learn the notifier service id and whether an exception listener is auto-registered. That file tells you what you get for free vs. what you must wire.

5. First use case: set credentials in .env/.env.local, deploy to staging, throw an intentional exception from one controller action. Confirm the notice lands in the Airbrake dashboard with a readable backtrace and the correct environment. If nothing arrives, it is almost always credentials, environment gating, or the host URI — not the code path.

Implementation Patterns

Let the kernel listener do the heavy lifting. The bundle registers an exception listener on kernel.exception; for uncaught exceptions you typically write no code at all. Verify in services.yml that the listener is enabled and that it is not deferred in a way that misses early bootstrap failures.

Monolog handler for logged errors. Route error/critical log entries to Airbrake via a Monolog handler so you capture errors you swallow with try/catch and log instead of throw. Two separate paths — listener for uncaught, handler for logged — are how you close the coverage gap.

Enrich context deliberately. The bundle advertises request and application context. Push environment name, deployment SHA, and user id/tenant into the notice so dashboards can filter. Set these once at boot (a kernel listener or an initializer) rather than in each controller.

Filter aggressively. Configure ignored exceptions (404s, AccessDeniedException, validation exceptions) so the dashboard reflects genuine incidents and not routine control flow. An unfiltered Airbrake project becomes noise within a week and everyone stops watching it.

Environment separation. Use distinct Airbrake project IDs (or at minimum the environment field) for staging vs. production. Never share a project ID, or staging noise masks production signal.

Local dev should not phone home. Disable the notifier outside staging/production via a config flag or by conditionally registering the handler. Nobody wants their dev exceptions alerting the on-call.

Integration with existing exception handling. If you already catch and log-and-continue in places, remember Airbrake will only see what reaches the listener or the Monolog handler — audit those catch blocks that swallow silently.

Gotchas and Tips

• Wrong framework. The single biggest gotcha: this package does not work in Laravel. Symfony bundles have no equivalent boot hook. Do not try to shoehorn it in.
• Maintenance and supply chain. Zero stars, zero dependents, and an unaccountable maintainer for the component that tells you when things break — it is itself your least-observed dependency. Budget an internal owner or fork it; do not depend on upstream fixes.
• Symfony version drift. Bundles from the Symfony 2/3 era frequently use container patterns removed in Symfony 5/6 and will not run on current PHP 8.x without patching. Check the PHP and Symfony constraints in composer.json before committing.
• Synchronous HTTP in the error path. Reporting fires inline on the request thread. If Airbrake is slow or down, every exception adds latency — precisely during the outage you are trying to observe. Push onto an async queue and apply a short timeout plus a circuit breaker.
• Error storms. A systemic failure generates thousands of notices per minute, magnifying outbound traffic and cost. Add sampling/rate-limiting and lean on Airbrake's aggregation rather than sending every occurrence.
• Silent drops. Notifiers typically swallow transport exceptions. Emit a metric or log a warning when reporting itself fails so you notice when telemetry is broken.
• Fatal/OOM/shutdown errors. These do not flow through kernel.exception. Confirm the underlying notifier registers a shutdown handler, or your most severe incidents go unreported.
• Config keys are authoritative from the extension, not the README. When a YAML key is rejected, open DependencyInjection/Configuration.php — the tree defines the exact names, required-ness, and defaults.
• Credentials in environment. Project API keys must come from secret storage, never a committed YAML file. Symfony's %env()% with .env.local (git-ignored) is the pattern; keep production keys in the platform's secret store.
• Debugging "nothing arrives." In order: (1) is the notifier enabled for this env? (2) are credentials correct and project ID numeric? (3) is the host correct for self-hosted vs. SaaS? (4) is the exception in the ignore list? (5) did the listener actually fire — temporarily var_dump or add a listener that logs to a file first. Credentials and env gating are the culprit 90% of the time.
• Extension points. The cleanest place to customise notice content is the notifier service or a decorating listener around it, not editing the bundle. Treat the bundle as source material for a thin owned wrapper rather than a dependency you modify in place.

Bottom line for a day-to-day workflow: if you are on Symfony and Airbrake is a fixed contract, this will get you uncaught-exception and logged-error coverage in an afternoon — but budget for the notifier's synchronous failure modes and treat the bundle as needing an owner. If you are on Laravel, or if Airbrake is not contractually mandated, skip it: wire the vendor's PHP SDK yourself (~50–100 lines) or move to a maintained, first-party-supported tracker and retire the question entirely.