Badaboom Laravel Package

Getting Started

Verify compatibility before installing anything. This package predates modern PHP tooling; open its composer.json on the tag you intend to use and confirm the php constraint. If it can't run on your PHP version, stop — forking is your only path forward.

composer require fp/badaboom

There is no Laravel auto-discovery, service provider, facade, or config file. You wire it manually in AppServiceProvider::register():

use BadaBoom\Boom;
use BadaBoom\ChainHandler\ChainHandler;

$this->app->singleton(Boom::class, function () {
    $boom = new Boom();
    $boom->addHandler(new ChainHandler([
        new class implements \BadaBoom\Adapter\AdapterInterface {
            public function handle(array $data): void
            {
                \Log::channel('slack')->error(
                    $data['exception']->getMessage(),
                    ['exception' => $data['exception']]
                );
            }
        },
    ]));

    return $boom;
});

Where to look first, in order:

1. README.md — the API shifted across releases; trust the tag you installed, not the docs at HEAD.
2. BadaBoom\Boom — the entry point that owns the handler chain and data collectors.
3. BadaBoom\ChainHandler\* — how handlers are composed and filtered.
4. BadaBoom\Adapter\AdapterInterface — the one extension point you'll actually implement.

First real use case: funnel uncaught exceptions into one place. In Laravel 11+ hook it via bootstrap/app.php:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (Throwable $e) {
        app(\BadaBoom\Boom::class)->catchException($e);
    });
})

That gives you a single seam where destinations can be added without touching controllers or jobs.

Implementation Patterns

Adapter-per-destination. Don't wire the built-in email/HipChat adapters directly into the request path. Write thin adapters that delegate to Laravel's logger or a queued job. Adapters are the intended extension seam — everything else is plumbing.

Level-based routing. Rather than one chain for everything, register a chain that routes by exception type or severity: criticals to Slack, warnings to the log, ValidationException-style noise dropped entirely. Do the filtering in the adapter (or a decorator around it) so the routing logic stays testable.

Attach data collectors for request context. Collectors are the real value-add over a plain Log::error — they gather $_SERVER, session, and environment state so adapters receive a populated $data array. Feed in current user and route explicitly:

$boom->addDataCollector(new class implements \BadaBoom\DataCollector\DataCollectorInterface {
    public function collect(array $data): array
    {
        $data['user_id'] = auth()->id();
        $data['route']   = request()->route()?->getName();
        return $data;
    }
});

Queue the slow work. Adapters run synchronously inside the exception path. If an adapter does network I/O (Slack, mail, HTTP), push a job and return immediately — otherwise you've added latency to every failing request.

Test with a capturing adapter. Swap the real chain for an in-memory adapter in tests and assert against $data. Because Boom is a singleton, $this->app->instance(Boom::class, $fake) is the cheapest way to verify context collection without mocking HTTP.

Bootstrap early for fatal-error coverage. Registering only inside report() misses fatals that never reach Laravel's handler. If a spike or legacy codebase needs those too, layer Boom on top of set_exception_handler() — but pick one integration point per process.

Gotchas and Tips

• Treat this as vendored code. With 4 stars and 0 dependents on record, expect no upstream fixes. Pin an exact version, be prepared to fork, and pick Sentry/Bugsnag/Flare if you're choosing a tool today.
• Handler exceptions cascade. If an adapter throws while handling an exception, you can recurse or fatally mask the original error. Wrap handle() in try/catch (\Throwable) and fall back to error_log.
• Data collectors must never throw. They run in a degraded state (no DB, possibly no session). Guard every lookup with ?? and avoid anything requiring a fully booted container.
• No vendor:publish, no facade, no config. Everything is manual wiring; nothing will be registered for you.
• Namespace is BadaBoom\, not Fp\. The composer name and namespace disagree — this trips up IDE auto-import every time.
• Verify the AdapterInterface signature against your tag before writing adapters. Older releases used handle(array $data) with no return type; newer PHP warns on the missing : void. Match whatever the installed version declares.
• Double-reporting risk. Registering both set_exception_handler and inside Laravel's report() sends every error twice. Choose one integration point.
• Debugging tip: temporarily swap your chain for a var_dump-and-die adapter to inspect exactly what $data contains before writing formatting logic against keys that may not exist.