Nova Bugsnag Laravel Package

Getting Started

The package is a Nova tool, not a notifier: bugsnag/bugsnag-laravel (or the Bugsnag PHP SDK) still needs to be installed and configured for errors to reach Bugsnag at all. napp/nova-bugsnag only reads error data back out via the Bugsnag Data Access API and renders it inside Nova.

Minimal path:

1. Install into the app that already has Nova (matching major version):

   composer require napp/nova-bugsnag
   

2. Publish the config and inspect it before touching env:

   php artisan vendor:publish --provider="Napp\NovaBugsnag\NovaBugsnagServiceProvider"
   

   Look for the auth token, organisation/project identifiers, and any cache/ttl keys. The exact keys are the first thing to confirm — the repo README is the source of truth and is short.
3. Set credentials. This package needs a Bugsnag Data Access API personal auth token (the one used for api.bugsnag.com), not the notifier API key the Laravel SDK uses. Put it in .env:

   BUGSNAG_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   

   Optionally scope it to a project/org ID if the config exposes them.
4. Register the tool in app/Providers/NovaServiceProvider.php:

   public function tools()
   {
       return [
           new \Napp\NovaBugsnag\NovaBugsnag, // check the exported class name
       ];
   }
   

5. php artisan config:clear && php artisan nova:publish (if the tool ships assets), then refresh /nova.

First use case: a lightweight on-call/triage tool — open the Nova panel, see the latest errors from your production release stage, and jump to Bugsnag only when you need stack traces. Treat it as a signal surface in Nova, not a replacement for the Bugsnag UI.

If the tool renders empty on first load, stop and verify the token and API reachability before reading the rest of this document — that's the failure mode 90% of the time.

Implementation Patterns

Restrict visibility rather than hiding the tool. Register it unconditionally and gate it, so the menu entry doesn't leak in the UI:

Nova::tools([new \Napp\NovaBugsnag\NovaBugsnag]);
// and in the tool class / via canSee:
Gate::define('viewBugsnagErrors', fn ($user) => $user->isOnCall());

If the tool doesn't ship a canSee, wrap it: subclass it and add public function canSee(NovaRequest $request).

Multi-project / multi-environment. Bugsnag orgs usually have separate projects per environment. If the config accepts a single project, instantiate multiple tool instances with different config (or a subclass that overrides the project ID) — one per environment, labelled Bugsnag (prod) / Bugsnag (staging) in the sidebar.

Deep-link from resources into Bugsnag. The highest-value pattern for day-to-day use: add a Nova action or field to User/Order/Tenant that builds a Bugsnag search URL using the identifier you send as user.id in the notifier:

Text::make('Bugsnag', function ($user) {
    $q = urlencode("user.id:{$user->id}");
    return "<a target='_blank' href='https://app.bugsnag.com/{$org}/{$project}/errors?filters[0][type]=eq&filters[0][filter]=search&filters[0][value]={$q}'>search</a>";
})->asHtml(),

This is the integration that makes the package worth installing — Bugsnag's own "user" tab is slow, Nova is already open.

Cache aggressively. The Data Access API is rate-limited and slow (500 ms–2 s per call). If the tool calls out on every page load, wrap or subclass the underlying client and cache the payload:

Cache::remember("bugsnag:{$project}:{$filter}", now()->addMinutes(5), fn () => $client->errors(...));

If the package doesn't expose the client, that's your first extension point (see below).

Pair with a Nova card. For dashboards, the tool itself is a full page; a small custom Card that shows "N errors in the last 24h" via the same client gives you the at-a-glance value without navigating.

Scheduled triage, not polling. Never fetch Bugsnag data inside a request that a user is waiting on if you can avoid it — a queued job writing counts into a table, read by a card, is more reliable and survives Bugsnag outages.

Gotchas and Tips

• Token type is the #1 pitfall. BUGSNAG_API_KEY (32-char notifier key) ≠ Data Access API token. Using the notifier key yields 401s or empty lists with no useful error in the Nova UI. Create a read-only, project-scoped personal token in Bugsnag → Settings → My account → Personal auth tokens.
• Silent failure. Nova tools that swallow HTTP exceptions show a blank table. Debug by hitting the API directly first:

  curl -H "Authorization: token $BUGSNAG_AUTH_TOKEN" \
    https://api.bugsnag.com/user/organizations
  

  If that fails, the package cannot work regardless of config.
• Nova version drift. With 12 stars and low maintenance, composer.json likely constrains Nova 1–3. On Nova 4/5 the tool component (dist/js/tool.js) and tools() registration semantics changed; you may need to composer require --ignore-platform-reqs and patch the compiled asset. Budget a fork.
• Assets are prebuilt. Many small Nova tools ship a compiled dist/ and no build step. Don't assume npm run dev works in vendor/; if the JS breaks, publish and patch the built bundle.
• Env caching. php artisan config:cache after any token change. A stale cached null token looks exactly like an invalid token.
• Bugsnag API surface is not stable. Bugsnag was acquired by SmartBear and has shifted API behaviour; endpoint fields (e.g. error_class, filters[] encoding) change. Pin the package version and add a smoke test that asserts a non-empty 200 from the API in CI.
• Security exposure. This surfaces production error data — stack traces, user emails, request payloads — inside your admin panel. Combine with IP allowlisting, SSO, and a canSee gate; do not ship it enabled for all Nova users.
• Extension points, in order of usefulness: published config (project/org IDs, cache TTL) → subclassing the tool to add canSee/cache → wrapping the injected HTTP client → forking the dist/ bundle. The package is small enough that forking is a legitimate choice; it's MIT-licensed and unlikely to receive upstream fixes.
• Verify before building on it: class name, config keys, and API endpoints as documented in the repo README. Everything above assumes the standard Nova-tool shape; confirm against the actual source in vendor/napp/nova-bugsnag/src before wiring it into production tooling.