Laravel Whoops Atom Laravel Package

Getting Started

This is an early package (0.2.1) whose release notes tell you almost everything you need to know up front: its service provider no longer loads in production. Treat it as a development/staging tool by default, and verify that assumption before designing anything around it.

Minimal steps:

1. composer require <vendor>/<package> — rely on Laravel's package auto-discovery; there is no reason to add the provider to config/app.php manually.
2. Run php artisan package:discover (or any artisan command) and confirm the provider registers locally.
3. Read the service provider first. Look for the environment guard — typically an $this->app->environment('production') / runningInConsole() check in register() or boot(). That single conditional is now the contract for the whole package.
4. Check whether a config file is publishable (php artisan vendor:publish --provider=...). If it ships one, publish and commit it; if it doesn't, skip config caching considerations for the package itself entirely.

First use case: boot your app locally, exercise whatever the package exposes, then run it under APP_ENV=production and confirm it goes quiet. Doing this on day one prevents the most common failure mode — discovering in a deploy that a feature you relied on has silently vanished.

Implementation Patterns

Trust the environment gate; don't re-implement it. Don't wrap your own if (app()->environment('production')) around calls into the package unless you also need a different fallback in prod. Duplicating the guard means two places to update when the package changes its policy.

Feature-flag at the call site. Because the package disappears in production, any code path that calls into it should be safe when it's absent. The clean pattern is a thin wrapper or a config-driven boolean:

if (app()->bound(SomePackageService::class)) {
    app(SomePackageService::class)->doThing();
}

This survives the package being unloaded in prod and survives you removing the dependency later.

Keep the deploy pipeline explicit about config caching. The change exists precisely because config caching was breaking. Standard deploy sequence still applies:

php artisan config:cache   # in the deploy, after env is set
php artisan route:cache
php artisan view:cache

What changed is that the package no longer tries to participate in that step. If you have a composer install --no-dev production build, the package's code is still installed but inert — that's intentional, not a misconfiguration.

Use it as a local/staging parity tool. If the package provides diagnostics, generators, or inspectors, run it against a staging environment that mirrors production data. Since it won't load in prod, staging (APP_ENV=staging) is your last realistic observation point.

Pin the version. At 0.2.x with a behavioral change to boot semantics, use a caret constraint you're comfortable with ("^0.2") and review changelogs before minor bumps. Early-zero-version packages make no semver stability promises on provider registration.

Gotchas and Tips

0.2.1 can be a silent breaking change. If you were using this package in production prior to 0.2.1, it worked (or half-worked). After upgrading, it will not load at all. Nothing throws — the provider simply never registers, so bindings, commands, routes, or Blade directives the package supplied are gone. Audit for hard dependencies before upgrading:

grep -rn "PackageNamespace" app/ config/ routes/ resources/

APP_ENV=production is common outside prod. Some staging and pre-prod environments are configured with APP_ENV=production and a separate APP_DEBUG. Those will now be treated as production and the package will not load. If you need the package on staging, change APP_ENV, don't hack the provider.

Clear the services cache after upgrading. bootstrap/cache/services.php is written by package:discover and is not regenerated by config:clear. Stale entries here are the classic cause of "I upgraded and the provider still/never loads":

php artisan config:clear
php artisan clear-compiled
composer dump-autoload
php artisan package:discover

Debugging whether it loaded. php artisan about lists loaded providers in recent Laravel versions; otherwise php artisan tinker and check app()->getLoadedProviders() or app()->bound(...). Don't infer from missing commands alone — a boot()-time guard fails differently from a register()-time one.

If you need it in production anyway, the correct escape hatch is publishing and overriding the package config if one exists (e.g. an enabled key), not subclassing the provider. Subclassing couples you to internals that just proved they can change in a patch release. If there's no config toggle, that's a deliberate stance by the maintainer — respect it or fork.

Extension points worth knowing. Published config (if present) is the intended surface. The provider's environment check is the second one, and it's the one that just changed — so treat any workaround that touches it as high-maintenance.