Laravel Stagefront Laravel Package

Getting Started

1. Install (staging only). Add it as a dev dependency so it never ships to production’s composer.json requirements by accident:

composer require codezero/laravel-stagefront --dev

As of 2.7.0 the package officially supports Laravel 11, so on L11 install ^2.7 (or pin an exact version — see Gotchas). If your deploy pipeline runs composer install --no-dev on production, that alone keeps it out of prod.

2. Publish and read the config first. This is a tiny package — the published config file is the entire API surface. Read it top to bottom before writing any code:

php artisan vendor:publish --tag=stagefront-config
# => config/stagefront.php

Expect keys along the lines of enabled, username, password (or hashed password), and possibly a redirect/allowlist. Match the exact key names in the file you actually get.

3. Register the middleware globally. A staging gate must catch every request, including 404s and routes you forgot about, so it belongs in the global stack — not on a route group.

Laravel 11+ (bootstrap/app.php) — supported from stagefront 2.7.0:

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\CodeZero\Stagefront\Middleware\Stagefront::class);
})

Laravel 10 and below (app/Http/Kernel.php):

protected $middleware = [
    // ...
    \CodeZero\Stagefront\Middleware\Stagefront::class,
];

4. Configure via env, not code. Put the real values in the config file and reference env() only inside config/stagefront.php:

STAGEFRONT_ENABLED=true
STAGEFRONT_USERNAME=client
STAGEFRONT_PASSWORD=correct-horse-battery-staple

First use case: you have a staging site on staging.example.com that you want to hand to a client for review before launch. You add the middleware, set one shared username/password in the staging .env, redeploy, and the whole site is gated. Done — no nginx config, no .htpasswd, no Forge UI changes.

Implementation Patterns

Environment-scoped enabling. Keep STAGEFRONT_ENABLED=false in .env.example and in any shared config, and only flip it true in the staging environment’s .env. Gate on environment in the config rather than relying on people remembering:

// config/stagefront.php
'enabled' => env('STAGEFRONT_ENABLED', app()->environment('staging')),

Deploy-pipeline integration. Set the credentials as environment variables in Forge/Ploi/Envoyer/your CI secrets, then run php artisan config:cache as the last deploy step. Because config is cached, the password lives in bootstrap/cache/config.php — treat that file as a secret and don’t commit it.

Per-environment credentials. PR preview environments (Laravel Vapor, Ploi preview sites, etc.) should each get a unique generated password injected by CI, so a leaked preview password doesn’t unlock every branch.

Local dev parity. If you want the gate locally to test the login flow, enable it in .env locally with a throwaway password; otherwise leave it off so php artisan serve doesn’t nag you.

Protect a subset of routes. If you only want to gate the app (and keep webhooks or health checks open), register the middleware on a route group instead of globally:

Route::middleware(\CodeZero\Stagefront\Middleware\Stagefront::class)->group(function () {
    // app routes
});

This is weaker overall, but useful when third-party callbacks (Stripe, Mailgun, uptime monitors) must remain reachable without credentials.

Test suite hygiene. Your feature tests will otherwise get redirected to the login page and fail mysteriously. Disable it in phpunit.xml:

<env name="STAGEFRONT_ENABLED" value="false"/>

If you do want to test the gate, write one dedicated test that asserts a 401/redirect without credentials and a 200 with them, then disable it everywhere else.

Client handover flow. For a demo, give the client a single shared credential and rotate it after the review period. If the package supports a “remember” cookie or session TTL, set it to something short (hours, not weeks) for client-facing staging.

Complement, don’t replace, real auth. Stagefront is a perimeter gate, not authorization. Keep Laravel’s own login for the app itself; stagefront just stops the public from reaching the login page at all.

Gotchas and Tips

env() outside config files breaks under config:cache. This is the number one failure mode. If the package or your own code calls env('STAGEFRONT_PASSWORD') from a middleware or service provider, it returns null once config is cached. Always read config('stagefront.password') in application code and keep env() strictly inside config/stagefront.php. If you change the password on the server, run php artisan config:clear && php artisan config:cache.

Laravel 11 support landed in 2.7.0 — check your constraint. If you pinned an older line (1.x/early 2.x) before upgrading the framework, the middleware registration path and/or service provider may not line up with L11’s bootstrap/app.php style. Bump to ^2.7 before or with the L11 upgrade, and re-run php artisan vendor:publish --tag=stagefront-config to see whether the config shape changed between your pinned version and 2.7.0 (diff, don’t blindly overwrite).

Middleware ordering matters. If the gate uses sessions (a login form rather than HTTP Basic), it must run after StartSession and EncryptCookies. Appending to the global stack is usually correct; prepending it to the very front will produce “Session store not set on request” errors or silently lose the login state. On L11, $middleware->append() puts it at the end of the global stack — the safe default.

Exclude the login route from the gate. If you register the middleware globally and the package serves its own login form via a route, that route must be exempt — otherwise you get an infinite redirect loop. Check the package’s route registration or exclude the path in config.

Assets aren’t protected. Anything in public/ served directly by nginx/Apache (images, compiled JS, uploaded files) bypasses PHP middleware entirely. If staging hosts sensitive uploaded documents, put those behind a controller or a server-level rule — stagefront won’t help.

HTTP Basic has no logout. If the package uses Basic auth, the browser caches credentials for the session and there’s no way to “log out” except closing the browser. Test with incognito windows or you’ll spend an hour convinced your password change didn’t apply.

API clients and webhooks will 401. Any external service hitting staging gets gated too. Exclude those paths, or use route-group scoping (above) for anything machine-facing.

Avoid plaintext passwords in cached config where possible. bootstrap/cache/config.php will contain the plaintext password. Prefer a hashed-password option if the package offers one (Hash::make(...) in the config), and otherwise ensure file permissions and deployment artifacts are locked down.

Debug pages leak. With APP_DEBUG=true on staging and the gate enabled, an error page can expose stack traces and sometimes env-derived config to anyone who gets past the password. Staging should still run with APP_DEBUG=false for client demos.

Audit before trusting. With ~22 stars, zero dependents, and a single maintainer, this is a small package. The 2.7.0 release is a single-issue change (“Add support for Laravel 11”, #12) — no breaking changes, no new features, no deprecations — so the review burden is low, but read the middleware source anyway (it’s a handful of files) and pin an exact version in composer.json:

"codezero/laravel-stagefront": "2.7.0"

not ^2.7, so a surprise update can’t quietly change auth behaviour. Since it’s MIT, forking it into app/Support is a perfectly reasonable hedge if you need long-term guarantees — especially if you’re on L11 and the maintainer’s responsiveness on future framework bumps is unproven.

Extension points to check after publishing. Vendor-published views (--tag=stagefront-views) let you restyle the login page with your brand for client demos; a config-level allowlist (if present) lets office/VPN IPs skip the password entirely, which is a common staging convenience.

It doesn’t cover non-HTTP entry points. Queue workers, scheduled commands, and artisan are unaffected — fine for its purpose, but don’t treat stagefront as “staging is now secure.” Pair it with network-level restrictions (VPN, IP allowlist) for anything genuinely sensitive.