Getting Started

Start with a migration decision, not an install. alt-three/bugsnag is archived, deprecated, Laravel 5-only, and last released in June 2016. For any new or maintained application, the correct first step is to use the official bugsnag/bugsnag-laravel package instead. Treat this package as something you only touch because it is already in a legacy composer.json.

If you have inherited it:

Confirm what you actually have:
```
composer show alt-three/bugsnag
```
Check the installed version, its Laravel constraint, and whether Composer reports it as abandoned.
Register the provider manually. This predates Laravel 5.5 package discovery, so add it to config/app.php:
```
'providers' => [
    // ...
    AltThree\Bugsnag\BugsnagServiceProvider::class,
],
```
If the package ships a facade, register the alias in the same file:
```
'aliases' => [
    'Bugsnag' => AltThree\Bugsnag\Facades\Bugsnag::class,
],
```
Verify the exact class names against the package's src/ directory before copying this; the repository has been renamed/moved and old blog snippets often reference the wrong namespace.
Publish and inspect the config:
```
php artisan vendor:publish --provider="AltThree\Bugsnag\BugsnagServiceProvider"
```
Then read config/bugsnag.php in full. The important keys are typically the API key, release-stage filtering, notify level, and any blacklist/filter settings.
Put the key in .env, never in config or source control:
```
BUGSNAG_API_KEY=your-key-here
```
Smoke-test with a deliberate exception in a non-production environment:
```
throw new \RuntimeException('Bugsnag bridge smoke test');
```
Confirm it appears in the Bugsnag dashboard before wiring up anything else.

Where to look first: the package's BugsnagServiceProvider (what it binds and whether it hooks the exception handler), config/bugsnag.php (runtime behavior), and your App\Exceptions\Handler (where reporting usually needs to be connected). Also check whether your app's handler extends the package's handler or calls the facade manually — this package does not magically cover every exception path.

First real use case: report uncaught production exceptions from App\Exceptions\Handler::report(), with the application environment and release stage set correctly. Everything else — custom metadata, user context, severity — is secondary.

Implementation Patterns

Centralize reporting in the exception handler. The most reliable pattern is to report from App\Exceptions\Handler::report() rather than scattering Bugsnag::notifyException() calls around the codebase:

public function report(Exception $e)
{
    if ($this->shouldReport($e) && app()->bound('bugsnag')) {
        \Bugsnag::notifyException($e);
    }

    parent::report($e);
}

Guard against double-reporting if the package also hooks into the handler. Pick one path and stick to it.

Use Laravel's $dontReport as the first noise filter. Validation exceptions, authentication exceptions, 404s, and other expected control flow should not become Bugsnag errors. Filter them in the handler before they reach the client. This is cheaper and more predictable than relying on the package's notify-level or release-stage config.

Add context at the point of failure. Old Bugsnag PHP SDKs support a callback/report object pattern. Typical shape:

\Bugsnag::notifyException($e, function ($report) use ($order) {
    $report->setSeverity('error');
    $report->setMetaData([
        'order' => [
            'id'     => $order->id,
            'status' => $order->status,
        ],
    ]);
});

Always confirm the exact callback signature in the installed SDK version; the Bugsnag PHP client API changed across major versions, and this bridge may pin an old one.

Set user context once per request. In middleware or a service provider, attach a stable identifier:

\Bugsnag::setUser([
    'id'    => (string) $user->id,
    'email' => $user->email,
    'name'  => $user->name,
]);

Avoid sending more PII than necessary. If you cannot configure filtering confidently, send only the ID.

Treat release stage as a first-class setting. Map APP_ENV to Bugsnag's release stage (production, staging, local) and configure the package to notify only for stages you care about. Otherwise local development and CI runs pollute the dashboard — or worse, staging errors become invisible because the stage filter excludes them.

Cover non-HTTP paths explicitly. Exceptions in queue jobs, scheduled commands, and console commands do not always pass through the HTTP exception handler. Report from job failed() methods or a global console hook if those paths matter. This is a common blind spot with old Laravel error bridges.

Make it testable. Bind a fake or null client in the test environment, or assert on a swapped client. A package this old often lacks a clean testing abstraction, so the pragmatic pattern is:

if (app()->environment('testing')) {
    // don't initialize the real client, or bind a stub
}

At minimum, ensure tests never send real events to Bugsnag.

Keep the integration thin. Wrap reporting behind a small application service or interface if you plan to migrate to bugsnag/bugsnag-laravel later. Given the package is archived, migration is not a question of if. A thin wrapper keeps the eventual swap to a few files.

Gotchas and Tips

This package is a dead end. It is archived, deprecated, and last released in 2016. It will not receive compatibility fixes for modern PHP or Laravel. The practical consequence: PHP 8 type changes, Laravel container changes, and updated contracts can break it in ways no one will patch. Do not build new features on it; budget migration time.

Composer will warn you it is abandoned. Expect Package alt-three/bugsnag is abandoned during installs. That is a useful signal to raise in code review. If you are temporarily stuck, consider forking it under your own namespace or using Composer's replace, but document the exit plan.

No auto-discovery. On Laravel 5.5+ you may assume the provider is registered automatically. It is not. Missing provider registration is the most common "nothing is being reported" cause; check config/app.php first.

Configuration caching bites. After editing config/bugsnag.php or .env, run:

php artisan config:clear
# or, in deployment:
php artisan config:cache

An empty or stale API key after a config cache is a classic silent failure.

Empty API key often means silent no-op. Some versions throw; others quietly do nothing. Add a startup assertion or log warning when BUGSNAG_API_KEY is empty in a non-local environment.

Double-reporting. If both the package's handler integration and your own report() call are active, you will get duplicate events. Check the dashboard for doubled occurrences after installation.

Watch what you send. Old error clients can be liberal about including request parameters, headers, and cookies. Configure the package's blacklist/filter settings or Bugsnag's dashboard filters for passwords, tokens, and authorization headers before going to production. Never assume default filtering covers your application's sensitive fields.

Release-stage filtering hides errors. If staging errors never appear, verify the configured notify release stages include staging. This is a frequent "Bugsnag is broken" false alarm.

Queues and memory. Older Bugsnag clients send synchronously by default. In long-running queue workers this can add latency or, in pathological cases, leak state between jobs. If you report from workers, verify behavior under load and consider resetting user context at the start of each job.

Debugging checklist when events do not appear:

Is the provider registered?
Is the API key present after config:cache?
Does the release stage match the allowed notify stages?
Is the exception in $dontReport or filtered by notify level?
Is the exception actually reaching report() (not swallowed earlier)?
Does \Bugsnag::notifyError('test', 'message') produce an event? If yes, the client works and the problem is the handler path; if no, it is config or network.

Extension point: bind your own client. The service provider typically binds a client instance into the container. If you need custom middleware, transport, or filters, resolve and decorate that binding rather than instantiating a second client. Read the provider source to see the exact binding key.

Facade or injection — pick one. The package likely exposes a facade, but injecting the underlying client (or your own wrapper) is more testable and makes the eventual migration to the official package far less painful. Prefer constructor injection in application services.

Pin and audit the dependency. Because there are zero dependents and no maintenance, treat this as a vendored legacy dependency. Run composer outdated and include it in dependency audits, but do not expect an upgrade path. The upgrade path is replacement.

Migration target. When you replace it, bugsnag/bugsnag-laravel is the supported successor. Most call sites map closely: notifyException, user context, metadata, and release stage all have equivalents. The main work is removing manual provider/facade registration, adopting the official config file, and retesting the exception-handler integration.

Bugsnag Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips