Lockout Laravel Package

Product Decisions This Supports

• Build vs. buy for operational kill switches. The core question this package answers is whether to hand-roll route lockout or use Laravel's native artisan down. Native maintenance mode is all-or-nothing; this package adds route-pattern targeting, IP/CIDR allowlists, and named/API route detection — which is precisely the layer teams end up writing themselves during their first incident.
• Incident response capability (MTTR reduction). A no-deploy lever to disable a failing subsystem (checkout, payments, a third-party integration) in seconds. The v6.1.0 failure-signaling fix — commands now fail without emitting success events when env persistence fails — is the difference between "we think we locked it out" and "we know we did." That directly supports on-call automation and alerting.
• Staged rollout and internal-only access. CIDR matching, now including IPv6, enables "expose to office/VPN/carrier ranges only." Dual-stack and mobile-network traffic is real; IPv4-only matching silently failed open or closed for a meaningful slice of users.
• Framework lifecycle roadmap. Laravel 13 support (PHP 8.3+) with retained 11/12 support maps cleanly onto a "stay on supported majors" commitment. Note the release explicitly flags Laravel 11 as outside security support — this decision is coupled to your Laravel upgrade plan, not independent of it.
• Deployment architecture decisions. The operational contract (rebuild config caches, restart queue workers/Octane after toggling) is a real constraint that should inform whether your toggle state lives in env or in a database/flag service.
• Prioritizing use cases. Best fit: emergency subsystem disable, internal-IP-only exposure, per-environment lockouts, third-party dependency outages. Poor fit: per-user, per-tenant, or percentage-based rollout.

When to Consider This Package

Adopt when:

• You need route-level or path-pattern lockout, not whole-application maintenance.
• You need IP/CIDR bypass lists (including IPv6) so internal staff retain access during a lockout.
• You want an operational lever usable by on-call without a deploy — and your team can tolerate a worker/Octane restart and config-cache rebuild afterward.
• Your configuration source of truth is the environment file and your deploy pipeline controls its permissions.
• You are on patched Laravel 12 or 13.

Look elsewhere when:

• Env files are read-only in production. The release calls this out directly: if APP_READ_ONLY comes from external environment variables, the toggle must be changed through your deployment system — the package cannot persist it. In that architecture, use a database- or service-backed flag instead.
• You need feature-flag semantics — per-user, per-tenant, cohort, or percentage rollout. This is route/IP scoped and won't model that.
• You need audit trails, approvals, or RBAC around who disabled what and why. Out of scope.
• You are pinned to Laravel 11. It's out of security support; the CI advisory exceptions are explicit framework-level carve-outs, not a statement about this package's security posture. Treat Laravel 11 as a dev-only target.
• Your pipeline cannot restart long-running workers. Stale state in queue workers or Octane is a correctness risk, not a cosmetic one.

How to Pitch It (Stakeholders)

To executives: A low-cost operational safety net that lets us disable a broken part of the product in seconds without shipping code — cutting time-to-recovery during incidents. It's actively maintained, tested across 11 PHP/Laravel combinations (86 tests, 184 assertions), and is ready for Laravel 13, so it supports rather than blocks our framework upgrade commitment. Adopting it is a small dependency bet against a recurring class of outage.

To engineering: Drop-in from v6.0.0 — additive compatibility plus bug fixes, no breaking changes. v6.1.0 hardens the parts you'd otherwise get wrong: atomic env writes that preserve existing file permissions, clearing of stale config/status caches, malformed CIDR rejection, literal route-pattern matching, and named/API route detection happening before global middleware dispatch. The failure semantics are honest — no success event if persistence fails. The trade-off is an explicit operational contract: rebuild config caches and restart workers/Octane after a toggle; --clear-cache remains accepted so existing scripts don't break.

To security/compliance: Requires PHP 8.2+ (8.3+ on Laravel 13), tested through PHP 8.5. Current Laravel 12/13 dependency audits are clean. The Laravel 11 CI advisory exceptions are enumerated upstream framework advisories and do not represent a change to application security policy — production should be on patched Laravel 12 or 13.