Laravel Blockade Laravel Package

Technical Evaluation

Architecture fit. Unchanged in substance. Blockade remains an HTTP-layer concern: a middleware that intercepts requests and returns a maintenance/WIP response before routing. It composes with middleware groups, requires no domain-code changes, and keeps presentation inside the app's theming system — now more so, since 1.1.0 adds publishable CSS, a PostCSS build step, and a dark-mode illustration driven by prefers-color-scheme. The overlap caveat still dominates: Laravel's first-party php artisan down ships a bypass secret, per-status customization, and a renderable closure. Blockade's differentiator remains "richer, self-hosted blockade page with less artisan/ops ceremony," not "can we show a maintenance page at all."

The maintenance signal moved slightly. The prior assessment was based on a last release of 2020-11-20; a 1.1.0 implies some renewed activity. That is a positive but weak signal — a cosmetic-only release after a multi-year gap tells us the maintainer is alive, not that the package is tested against modern Laravel. Treat the maintenance risk as downgraded from "abandoned" to "unverified," not "resolved."

Integration feasibility. Mechanically still low effort, but 1.1.0 adds a step: php artisan blockade:install must be re-run on upgrade to publish new assets, and the package now expects a PostCSS build pipeline for its stylesheets. That means integration touches the front-end asset pipeline, not just Composer config and middleware registration, and it makes upgrades non-idempotent — a published-asset directory that diverges from upstream is a new drift surface. The version-drift risk is unchanged and unresolved: the release notes are silent on illuminate/* constraint changes, PHP version support, and the Laravel 11 bootstrap/app.php middleware registration model. Assume a spike is still required.

Technical risk. The three material risks from the prior assessment stand unchanged:

1. Unmaintained-adjacent code on the availability-critical path. A cosmetic release does not constitute community scrutiny of the bypass logic. Zero dependents still means nobody has audited the middleware.
2. Bypass mechanism trust. Any secret/allowlist used to let staff through must be timing-safe, out of version control, and not leaked via logs or URLs. Verify, don't assume.
3. State locality. If the enable/disable flag lives in config or .env, state diverges per node and per deploy.

Release 1.1.0 introduces one new, lower-severity risk: published static assets are now part of our surface. Customized CSS and SVGs in public/ are ours to maintain, and the blockade:install command will overwrite them on upgrade unless we've layered customizations correctly — the same fork-drift problem we already have with views, now extended to stylesheets. Dark mode also introduces a rendering path that must be checked against our actual theme, not assumed.

Key questions. Carried forward, plus the new asset surface:

• Where is blockade state stored — config, cache, or DB — and is it shared across all app instances?
• What is the bypass mechanism (secret token, IP allowlist, authenticated session) and does it work on API routes and health probes?
• Does it return a proper 503 with Retry-After and support JSON negotiation for API clients?
• Is the check global or attachable to route groups so internal/admin routes stay reachable?
• Does 1.1.0 widen the Laravel/PHP support matrix, and is there CI asserting it? The release notes don't say.
• Where do published CSS/SVG assets land, and does blockade:install overwrite customizations? Determines whether our branding survives an upgrade.
• Does the PostCSS build run at install time or require a Node toolchain in our pipeline? A Node dependency in a PHP deploy is a real cost.
• Does dark mode degrade gracefully if our layout doesn't define the relevant CSS variables?
• Who owns published views and assets once customized, and how do we detect upstream drift?

Integration Approach

Stack fit. Unchanged. Good fit for a conventional Laravel monolith on PHP 8.x with a shared cache and Blade front end; poor fit for multi-tenant per-scope blockade or JSON-only 503 paths. 1.1.0 slightly improves fit for teams with an existing PostCSS/Tailwind pipeline and native dark-mode theming — and slightly worsens it for teams without a front-end build step.

Migration path. Ranking unchanged:

1. Native-first (recommended). php artisan down --secret --render=errors::503 plus a custom Blade view. Zero dependency, first-party support, covers 80–90% of the need — including dark mode, which is a handful of prefers-color-scheme rules in our own stylesheet. Cost: toggling is artisan/ops-driven rather than a config flag. 1.1.0 does not change this calculus; it reinforces it, since the new features are precisely the ones we'd implement ourselves in an afternoon.
2. Fork/vendor. Copy into app/Support/Blockade or a path repository. Retains middleware ergonomics and customization with explicit ownership. If we fork, fork after 1.1.0 so we inherit dark mode and the asset structure in one pass.
3. Adopt upstream as-is. Still only viable if the version matrix resolves on the target Laravel and the bypass path passes review. 1.1.0 does not demonstrate that either condition holds.

Compatibility. Pin an explicit Laravel/PHP matrix before committing and re-test it against 1.1.0 specifically — cosmetic releases are exactly where framework constraint bumps get skipped. Verify middleware alias registration (Kernel vs bootstrap/app.php), cache driver semantics, view compatibility with our layout components, and now the asset pipeline: whether blockade:install runs cleanly, whether it needs Node/PostCSS available, and whether it is safe to re-run.

Sequencing.

1. Spike in a throwaway branch — verify 1.1.0 installs and boots on the target Laravel.
2. Run blockade:install in the spike and inspect exactly what it publishes and where; confirm re-runnability and overwrite behavior.
3. Code review of the middleware and bypass path (security sign-off).
4. Decide native vs fork vs adopt; document the rationale.
5. Implement toggle state, bypass, custom views and styles; add tests for blockade-on and bypass-on paths.
6. Wire into the deploy/incident runbook, including the blockade:install step on any future upgrade.
7. Load-test the blockade path; verify health-check, static-asset, and dark-mode rendering behavior.

Operational Impact

Maintenance. Unchanged in direction, slightly larger in scope. We own this code on any path. If forked or adopted, assign a named owner, add it to the quarterly dependency review, and now also track published asset and view drift — 1.1.0 is a concrete example of an upstream change that lands in our repo rather than in vendor/. Record the upgrade ritual: composer update, then php artisan blockade:install, then diff published files against our customizations. If native, maintenance stays near zero and the dark-mode feature becomes ~10 lines of our own CSS — a strong argument for native.

Support. No vendor, no SLA, no upstream triage. The release note "please run the install command" is documentation-shaped, not support. Internal on-call remains the support model. Extend the internal runbook to cover the asset-publish step, not just enable/bypass/force-disable.

Scaling. No change from the prior assessment, but worth restating because 1.1.0 adds static files to the picture: the blockade check must be a single cheap cache read, short-circuiting before session/auth initialization; health/liveness endpoints must be excluded or a blockade will mark every node unhealthy and trigger a worse outage; the 503 must not be edge-cached past the end of the blockade. New with 1.1.0: verify the published CSS/SVG are served with sane cache headers and that a blockade doesn't leave the maintenance page unstyled when assets are cached-busted or blocked.

Failure modes.

• Cache store unavailable → fail-open or fail-closed? Decide explicitly and encode it. Fail-open exposes the site; fail-closed turns a cache blip into a full outage.
• Stale toggle left on after an incident — mitigate with a hard TTL and an alert.
• Per-node state drift if config-based — mitigate by moving state to shared cache.
• Bypass secret leakage via URL logs, referrers, or error pages.
• Wrong content type — API clients receiving HTML instead of a JSON 503.
• Middleware ordering conflicts with auth/session causing redirect loops on the blockade page.
• New: upgrade clobbers branded assets. blockade:install overwriting customized CSS/SVG, producing an unstyled or off-brand maintenance page at the exact moment it's customer-facing. Mitigate by customizing in our own stylesheet layered on top, or by vendoring the package.
• New: PostCSS/Node unavailable in CI or deploy, leaving stylesheets unpublished or stale.

Ramp-up. A mid-level Laravel engineer can integrate and customize in roughly half a day; 1.1.0 adds maybe an hour for the asset pipeline if the team already runs PostCSS, and a meaningful unknown if it doesn't. The security review of the bypass path and the ops runbook remain the real cost — call it 2–3 days end-to-end including the spike. Documentation debt is still the main drag, now with one more step to document.

TPM recommendation. Unchanged: treat this as a design reference, not a dependency. Ship the native Laravel down mechanism with a custom 503 view — including the dark-mode styling, which is trivial in our own CSS — or fork the middleware if the richer toggle surface is a genuine requirement. Release 1.1.0 adds polish, not capability we can't build in an afternoon, and it introduces asset-pipeline and upgrade-ritual surface without answering a single one of our open questions about framework support and bypass security. The recommendation to keep an unmaintained-adjacent package off the request-blocking path stands.