Honeybadger Php Laravel Package

Getting Started

Minimal setup in a Laravel app:

composer require honeybadger-io/honeybadger-php

Add credentials to .env (never hardcode them):

HONEYBADGER_API_KEY=xxxxxxxx
HONEYBADGER_ENV=production

Bind the client once as a singleton so you get one instance per request:

// app/Providers/AppServiceProvider.php
use Honeybadger\Honeybadger;

public function register(): void
{
    $this->app->singleton(Honeybadger::class, fn () => Honeybadger::new([
        'api_key'      => config('services.honeybadger.api_key'),
        'environment'  => app()->environment(),
        'project_root' => base_path(),
        'version'      => config('app.version'),
        'logger'       => null, // see Gotchas: avoid log-loop
    ]));
}

Where to look first. The README's config table is the real API surface — the class itself is thin. Then read src/ in this order: the client entry point (Honeybadger::new() factory and notify()), the config/options object, the Handlers/ directory (error + exception handlers), and Filters/. The tests/ directory is usually the most complete usage documentation for this package, since the public docs are oriented toward the Rails gem and the Laravel wrapper.

First use case. Report unhandled exceptions with context. Hook into Laravel's exception handler rather than calling notify() from every controller:

// bootstrap/app.php (Laravel 11+) or app/Exceptions/Handler.php
public function register(): void
{
    $this->reportable(function (Throwable $e) {
        app(Honeybadger::class)->notify($e, [
            'context' => ['user_id' => auth()->id()],
            'tags'    => [request()->route()?->getName()],
        ]);
    });
}

Note: if you are on Laravel, check honeybadger-io/honeybadger-laravel first — it wraps this library and gives you a service provider, config file, and log channel out of the box. Use this core package directly when you need control over bootstrapping, are on a non-Laravel PHP app, or want a thinner dependency.

Implementation Patterns

Wrap, don't scatter. Put a small ErrorReporter service in front of the client. It keeps notify() calls consistent and gives you one place to add tags, scrub data, and no-op in local/testing:

final class ErrorReporter
{
    public function __construct(private Honeybadger $client) {}

    public function report(Throwable $e, array $context = []): void
    {
        try {
            $this->client->notify($e, [
                'context' => $context + [
                    'user_id'    => auth()->id(),
                    'request_id' => request()->header('X-Request-Id'),
                    'job'        => $context['job'] ?? null,
                ],
            ]);
        } catch (Throwable) {
            // never let telemetry break the request
        }
    }
}

Middleware for request context. Set the user, route, and tenant once per request so every subsequent notify() carries it, rather than threading arrays through call sites.

Queue jobs. Exceptions in queued jobs never hit the HTTP exception handler. Use Queue::failing() or the JobExceptionOccurred event to report with job class, queue name, attempts, and payload ID (not the payload). This is the single highest-value integration after the exception handler — most production errors in a Laravel app live here.

Monolog channel. If the library ships a Monolog handler, registering it as a dedicated honeybadger log channel lets you report Log::channel('honeybadger')->error(...) alongside exception reporting. Keep it on its own channel, not stacked onto stack.

Filtering. Configure filters once at construction for passwords, tokens, Authorization headers, and card fields. Configure excluded exceptions for the noisy-but-expected classes: ValidationException, AuthenticationException, ModelNotFoundException, NotFoundHttpException. Without this you will burn quota and train your team to ignore the dashboard.

Custom (non-exception) notifications. For business-rule failures that aren't exceptions, either report a purpose-built exception subclass or use whatever custom-message API the current version exposes — check the README for the exact method, since this has changed between major versions. Tags plus a message string are what make these searchable later.

Environment gating. Report from staging and production; disable entirely in local and in test suites ('environment' => 'local' and a null reporter binding). Reporting from tests pollutes the project and slows the suite.

Testing. There is no Honeybadger::fake() here. Bind a test double in the container:

$this->swap(ErrorReporter::class, $spy = Mockery::spy(ErrorReporter::class));
// act...
$spy->shouldHaveReceived('report');

Assert on your own wrapper, not on the vendor client — that keeps tests stable across package upgrades.

Gotchas and Tips

• Double reporting. If you use both the Laravel wrapper and this library with 'handler' => 'exception' configured, plus your own reportable() hook, every exception is sent two or three times. Pick exactly one reporting path.
• Log recursion. The client accepts a PSR-3 logger. If you pass Laravel's logger and you also wire a Honeybadger Monolog handler, a failed send can log, which sends, which fails. Pass null or a null logger.
• Global context leaks in long-running processes. Under Octane, or in a queue worker, a singleton client persists across requests/jobs. Anything you stash as context on the first request bleeds into the next. Reset context at the start of each request/job (JobProcessing, Octane's RequestReceived), or bind the client as scoped instead of singleton.
• project_root matters. Without it, stack traces show container paths and source snippets are omitted. Set it to base_path(); in Docker make sure the code is at the same path at report time as at deploy time.
• Filters are construction-time, not call-time. You cannot add a filter for a single notify() call. Decide filtering at boot. Also, filtering is key-based and depth-limited — nested or serialized payloads can still leak. Don't put raw request bodies in context.
• excluded_exceptions is a literal class list. Subclass inheritance is not reliably followed; list the exact classes you want silenced, including framework subclasses.
• PHP error handler chaining. Letting the library call set_error_handler can conflict with Laravel's own handler and silently swallow warnings. Prefer exception reporting plus explicit notify() for the warnings you care about.
• Version churn. This package has had breaking reorganizations between majors (factory/naming changes, handler restructuring). Pin the major version in composer.json and read the CHANGELOG before every bump; the README often documents only the latest API.
• Fail-open, always. Wrap every call. A network timeout or a malformed payload must never turn a handled 500 into a fatal. Set a short timeout on the HTTP client if the library exposes one (or via Guzzle options).
• Endpoint/proxy config. Self-hosted Honeybadger, air-gapped networks, and corporate proxies require overriding endpoint and possibly disabling SSL verification. Verify connectivity with a single throwaway notify(new Exception('ping')) from staging before rolling out.
• Quota and noise. There is no client-side sampling out of the box. Excluded exceptions plus disciplined context are your only levers before the bill arrives; consider a wrapper-level random_int() sample for high-volume, low-severity paths.
• Low-traffic package caveat. At this size, expect edge cases to be undocumented. When behavior is unclear, read the test suite and the request-building code — that is the ground truth, not the README.