Honeybadger Laravel Laravel Package

Getting Started

• Install with composer require honeybadger-io/honeybadger-laravel, then run php artisan honeybadger:install. It publishes config/honeybadger.php, prompts for your API key, writes HONEYBADGER_API_KEY into .env, and fires a test notification.
• The service provider is auto-discovered on Laravel 10/11/12 — no manual registration in config/app.php. Set HONEYBADGER_ENVIRONMENT (or let it fall back to APP_ENV) per environment and keep the key out of the repo.
• Confirm the wiring end-to-end with php artisan honeybadger:test before touching any code, and again after upgrading to v5.1.0 — this release changes the default event pipeline, so verify what actually lands in the dashboard.
• Look first at config/honeybadger.php: the handlers array (what is captured automatically), the events section (Insights telemetry, now on by default), and the exceptions filtering rules. That file, not your Handler class, is where most day-to-day behaviour is tuned.
• First real use case: ship a staging deploy and confirm unhandled exceptions surface with useful context. Then add a Honeybadger::context([...]) call in a middleware to attach user_id, tenant, and request identifiers — this is the highest-value change you can make in the first hour.
• Manual reporting is a facade call away: Honeybadger::notify($throwable) for caught exceptions, Honeybadger::addBreadcrumb('message', ['category' => 'custom', 'metadata' => [...]]) to enrich the trail leading to a fault.

Implementation Patterns

• Exceptions: let the handler do the work. Unhandled exceptions are reported automatically via Laravel's exception handler integration. Reserve manual notify() for caught exceptions you deliberately swallow (third-party API failures, webhook processing) where the surrounding context is more useful than a stack trace.
• Context middleware. Register a middleware that calls Honeybadger::context(['user_id' => auth()->id(), 'tenant' => tenant()->id, 'request_id' => $request->header('X-Request-Id')]) early in the stack. In stateless requests it's implicitly per-request; see the long-running caveat below.
• Insights events as business telemetry (new default in 5.1.0). Events now flow without opt-in, so Honeybadger::event('order.completed', ['order_id' => $order->id, 'total_cents' => $order->total]) is a cheap way to get queryable product telemetry next to your errors. Use it for low-cardinality, meaningful domain moments — signups, payment outcomes, integration failures — not for debug chatter.
• Logs to Insights. Add a honeybadger channel in config/logging.php and use Log::channel('honeybadger')->warning(...) for conditions that aren't exceptions but still deserve visibility (deprecated API usage, degraded dependency, retry exhaustion). With 5.1.0's defaults, check whether your existing log events are already being forwarded before adding duplicate channels.
• Queue jobs. Job failures are reported automatically with the job payload and attempt count. Add domain context inside handle() rather than in the constructor, since serialized properties may contain sensitive data. If you need per-job grouping, set a custom fingerprint or tag via context keys.
• Scheduled tasks / check-ins. Wire Honeybadger::checkin('nightly-reconcile') into the task's success callback (->onSuccess() / ->then()) so Honeybadger alerts on absence of runs, not just failures. This catches a silent scheduler or a hung worker that no exception would ever surface.
• Deploy tracking in CI. Add php artisan honeybadger:deploy --environment=production --revision=$GIT_SHA to your pipeline (Forge/Envoyer deploy script, GitHub Actions, etc.). This needs the personal API key, not the project key — the single most common source of 401s here.
• Testing. Swap the client for a fake/spy in your test suite and assert on recorded notifications rather than hitting the network. v5.1.0 fixes mock instance ordering, so container-resolved assertions now target the correct instance — if you previously worked around ordering flakiness in tests, retry without the workaround.
• Octane / long-lived workers. Context set during one request or job can bleed into the next. Reset context and breadcrumbs in RequestTerminated/JobProcessed listeners, or scope them tightly inside the middleware/job that sets them.

Gotchas and Tips

• Insights is now on by default (the 5.1.0 headline). Events that were previously silent — logs, breadcrumbs, outgoing HTTP calls, and anything you emit with Honeybadger::event() — now flow unless you turn them off. Before upgrading production: audit the events block in config/honeybadger.php, confirm no request bodies, headers, or user identifiers are being shipped that shouldn't be, and disable in local/testing. Expect a data-volume (and quota) change even if you change nothing else.
• Verify, don't assume, after the upgrade. Run honeybadger:test and check the Insights view specifically — a green "exception arrived" signal doesn't prove the event pipeline is working.
• Noise control happens in two places. Use Laravel's $dontReport / $exceptions->dontReport() for classes you never want, and the package's exceptions config for filters (ignored messages, environment gating). Validation and 404-style exceptions are already excluded by Laravel's default reporting rules — don't re-report them from custom middleware.
• Config caching bites at deploy time. php artisan config:cache freezes HONEYBADGER_* values. Changing an env var on Forge/Envoyer without re-caching or redeploying leaves the old value live, which looks exactly like "the key is wrong."
• Buffered sends can be lost. Events are batched and flushed at the end of the request lifecycle. In CLI commands, exit()/dd() paths, or fatal-error scenarios, call Honeybadger::flush() (or the events-specific flush) before terminating, or you'll debug missing data for an hour.
• project_root and containers. Stack-trace file paths are made relative to project_root (defaults to base_path()). If you build in one directory and run in another (multi-stage Docker), paths won't line up and grouping/source links degrade.
• Sensitive data hygiene. Filter request parameters and job payloads at the config level rather than remembering to scrub at every call site; treat the API key as server-side only and never expose it in Blade/JS — the browser SDK is a separate integration with its own key.
• Extension points to bookmark: the honeybadger log driver for non-exception signals, Honeybadger::addBreadcrumb() for custom trails around flaky integrations, and check-ins for anything scheduled. Combined with the now-default event stream, these cover most "it broke and nobody knew" cases without writing custom alerting.