Env Alert Laravel Package

Getting Started

Install the package via Composer:

composer install defstudio/env-alert

The service provider is auto-discovered via Laravel package discovery — no manual registration in config/app.php is required on Laravel 8+. Publish the config file so you can tune the behavior:

php artisan vendor:publish --tag=env-alert-config

This should drop a config/env-alert.php file. Look there first — it's where you control:

• Which environment names trigger the ribbon (typically production, but you can customize)
• The ribbon text and color
• Whether the ribbon is enabled at all (useful for a hard kill switch)

The first use case is straightforward: keep the ribbon enabled on your production/staging deployments as a visual guardrail for developers and ops staff, and disabled in local dev where it would just be noise. Most teams enable it in production and staging but suppress it locally.

If the package ships a Blade component, add it near the end of your main layout:

{{-- resources/views/layouts/app.blade.php --}}
<body>
    @yield('content')
    <x-env-alert />
</body>

If it relies on middleware injection instead (check the config for a middleware or enabled key), no view change is needed — the ribbon is appended to </body> automatically on HTML responses.

Implementation Patterns

Environment-gated enablement. Don't hardcode the environment name in code; read it from config:

// config/env-alert.php
'environments' => ['production', 'staging'],

Then in your .env for each deployment, ensure APP_ENV=production (or staging) so the package activates automatically across all environments without per-environment builds.

Per-user suppression. Because the ribbon can be genuinely alarming to end users, combine the package's environment gate with an authorization check. If the package supports a closure ('visible' => fn () => auth()->user()?->isDeveloper()), use it so only internal staff see the ribbon:

'visible' => fn () => auth()->check() && auth()->user()->is_admin,

This is the single most useful pattern — you get the safety ribbon for developers without alarming customers.

Filament / Livewire integration. Since the ribbon is injected into the full HTML document (not Livewire re-renders), it's compatible with Filament panels and Livewire apps — it lives outside the Livewire root component, so it survives DOM morphs. If the package provides a Filament plugin or render hook, prefer that (e.g. ->renderHook(PanelsRenderHook::BODY_END, ...)) so it works on full-page and SPA navigation.

Staging parity. Use the same config across staging and production but vary the ribbon text per environment via a config value or an environment-aware callback so testers can tell which is which:

'label' => app()->environment('production') ? 'PRODUCTION' : 'STAGING',

Local dev opt-in. For demos and screen recordings, allow local activation via a .env flag rather than editing config:

'force' => env('ENV_ALERT_FORCE', false),

Gotchas and Tips

It only works on HTML responses. Middleware-injection packages detect Content-Type: text/html and append the ribbon. JSON API routes, downloads, and streamed responses will never show it — don't expect it to appear in API debugging. If your SPA fetches HTML fragments, you may need to render the Blade component explicitly.

APP_ENV mis-set on servers is the #1 silent failure. If your production server reports APP_ENV=local (a common copy-paste artifact from a .env scaffold), the ribbon silently won't appear — and conversely a dev box with APP_ENV=production will suddenly show it. Verify with php artisan about or php artisan tinker --execute="dump(app()->environment());" on the actual server.

Config caching will bite you. After any config change run php artisan config:clear (and re-run config:cache in deployment). A stale cached config is the most common reason "the ribbon won't turn off" — teams disable it in config/env-alert.php but forget the cache.

Inline styles vs CSP. The ribbon typically ships with inline CSS (style="..."). If you enforce a strict Content-Security-Policy, add style-src 'unsafe-inline' or a matching SHA-256 hash, or the ribbon renders as an unstyled block. Check the package's stylesheet — if it publishes an asset, prefer that.

Middleware ordering in Laravel 11+. If auto-injection relies on middleware, ensure it's registered in bootstrap/app.php's ->withMiddleware() and runs after the session/auth middleware (so the visibility closure can see the authenticated user). Placing it too early yields a null user and the ribbon may not appear for admins.

Stacking with debug toolbars. If you use Laravel Debugbar or Ignition, the ribbon may overlap or be hidden behind fixed-position elements. Adjust the position/z-index config if the package exposes them, or verify the ribbon isn't rendered off-screen on small viewports.

Extension points. If the ribbon markup is customizable, publish the Blade view (--tag=env-alert-views) rather than fighting CSS overrides. If the package exposes events or a custom renderer, hook into that — but for a 10-star package, expect a small surface area and prefer wrapping it in a tiny local Blade partial you control, so you can swap the package later without touching every layout.