Privat Laravel Package

Getting Started

1. Install the package

   composer require code16/privat
   

2. Publish the config (only if you plan to customize; the defaults work out of the box)

   php artisan vendor:publish --tag=privat
   

   This drops a config/privat.php where you control the password source, the middleware behavior, and any excluded paths.

3. Set the password in your environment file. The package reads from a config key that defaults to an env var (typically something like PRIVAT_PASSWORD):

   PRIVAT_PASSWORD=my-secret-staging-pass
   

   Commit this to your .env.example as an empty placeholder so other devs on the team know it exists, but never commit the real value.

4. Enable the middleware. In modern Laravel (11+) you can register it globally in bootstrap/app.php:

   ->withMiddleware(function (Middleware $middleware) {
       $middleware->append(\Code16\Privat\Middleware\ProtectWithPassword::class);
   })
   

   Or, on older versions, in app/Http/Kernel.php under $middleware. If you only want it on certain routes, add it to a route group instead — see Implementation Patterns.

5. First use case: ship the exact same middleware config across all your non-production environments. Your team gets a shared-password gate over the whole staging site; production is untouched because the password env var is empty there (the middleware short-circuits when no password is configured).

Once installed, visit the app in an incognito window — you should be redirected to a password form. That's the sanity check.

Implementation Patterns

Global gate for the whole site (most common). Register the middleware globally and protect every request. This is the "we deployed to staging, don't let Google index it" pattern. Pair it with noindex headers if SEO leakage is a concern.

Route-group gate. When you only want to protect the admin area, backend routes, or a specific set of feature routes during development:

Route::middleware(['privat'])->group(function () {
    Route::get('/admin', AdminController::class);
});

Adjust the alias to whatever the package registers (check config/privat.php — many similar packages register an alias like privat or protect).

Environment-scoped enablement. Guard the middleware registration itself so it never runs in production:

if (! app()->isProduction()) {
    $middleware->append(ProtectWithPassword::class);
}

This is safer than relying solely on an empty password — it makes intent explicit and avoids a misconfigured production env exposing a password prompt that shouldn't be there.

Bypass for authenticated users. If your app has real Laravel auth, add a check so logged-in developers/support staff skip the gate. Many password-gate packages expose a callback or let you order middleware so auth runs first; if not, wrap it in a small custom middleware that calls the privat middleware conditionally:

if (Auth::check() && Auth::user()->isDeveloper()) {
    return $next($request);
}
return app(ProtectWithPassword::class)->handle($request, $next);

Exclude machine endpoints. Webhooks (Stripe, GitHub), health checks (/up), and asset/image routes must be excluded or they'll break. Exclusions usually belong in config/privat.php under a except / whitelist array. Keep this list tight — every excluded path is a hole.

Per-environment passwords. Set different values per environment in your CI/deploy secrets:

• .env.staging → PRIVAT_PASSWORD=team-shared
• .env.preview → PRIVAT_PASSWORD= (or per-PR generated value if the package supports it)

This way a leaked staging password doesn't unlock your preview environments.

Combining with basic auth or IP allow-list. If the package supports HTTP basic auth mode as an alternative to the form, prefer it behind a reverse proxy (Caddy/nginx) so assets and everything are covered at the edge. The middleware is application-layer only — see gotchas.

Gotchas and Tips

• Assets and static files bypass middleware. If your images, compiled JS, or public PDFs live in public/ and are served directly by nginx, the password gate won't protect them. For real privacy, put the gate at the reverse-proxy level or serve those files through a controller. This package is a "keep out casual visitors" tool, not a security boundary.

• Config caching bites you. After changing PRIVAT_PASSWORD on a server, run php artisan config:cache. If the config is cached, the old password keeps winning and you'll spend twenty minutes debugging a password that "should" work.

• Middleware ordering matters. If you place the gate after auth middleware and rely on session, unauthenticated users may hit your login controller before the gate fires. Put the password middleware early in the stack so it short-circuits before your app's own auth/session logic does unexpected things.

• Sessions must be functional. If the package uses session-based unlock (a login form that sets a session flag), then SESSION_DRIVER=array or a broken database session store will make users re-enter the password on every request. Check the session driver when "it doesn't remember me" bugs appear.

• Excluded paths are the usual source of bugs. A webhook returning 302s or a 401 on /.well-known/ will look like the package is broken but is really a whitelist gap. When something mysteriously breaks, add the path to except first and confirm.

• Testing. Feature tests that hit protected routes will get the password form instead of your expected response. Either set PRIVAT_PASSWORD= (empty) in phpunit.xml's env block to disable the gate, or add the test client's session flag in a test trait. Empty password should disable the middleware entirely — verify that behavior matches your config.

• Don't treat it as auth. There's no user identity, no roles, no audit trail. If you need anything more than "shared secret to look at staging," use Laravel's real authentication or put the whole site behind HTTP basic auth at the proxy. This package is deliberately small; extend it via the config's callback/hook points rather than forking.

• Preview deployments. For ephemeral per-PR previews, either generate a random password per deploy and surface it in the PR comment, or accept that previews are public. Rotating a shared password across previews is a recipe for team confusion — automate it or don't do it.

• Logout / re-lock. If you need a "lock again" button, check whether the package exposes a route or a session key you can forget. Otherwise you'll need to clear cookies manually, which is fine for a dev tool but surprising if you expect a logout link.