- How do I install romanzipp/laravel-blockade in a Laravel application?
- Install it with composer require romanzipp/laravel-blockade, then run php artisan blockade:install to publish the package config and the CSS and SVG assets that ship with version 1.1.0. After that you register the Blockade middleware in your HTTP kernel or, on Laravel 11, in bootstrap/app.php. The middleware intercepts requests before routing, so it composes with existing middleware groups and requires no changes to your domain code.
- Does Laravel Blockade support Laravel 11 and the bootstrap/app.php middleware registration model?
- The 1.1.0 release notes do not state which illuminate/* constraints or PHP versions are supported, and they say nothing about the Laravel 11 bootstrap/app.php registration model. Mechanically the package is a standard HTTP middleware, so appending it in bootstrap/app.php should work, but that is an assumption rather than a verified claim. Run a short spike against your exact Laravel and PHP versions before committing, and check whether the repository has CI asserting the support matrix.
- What is the difference between Laravel Blockade and php artisan down?
- Laravel's first-party php artisan down already ships a bypass secret, per-status customization, and a renderable closure, so Blockade's value is not that it can show a maintenance page at all. Its differentiator is a richer, self-hosted blockade page with less artisan and ops ceremony, plus publishable CSS and a dark-mode illustration as of 1.1.0. If you only need a bare maintenance response with a staff bypass, the built-in command is likely enough.
- How does the bypass work so staff can still reach the app during a blockade?
- The package lets you configure rules and a bypass so specific traffic gets through, but the available material does not pin down whether that is a secret token, an IP allowlist, or an authenticated session. Whatever it is, verify the comparison is timing-safe, keep the secret out of version control, and confirm it is never written to logs or exposed in URLs. Also test that the bypass behaves correctly on API routes and health probes, not just browser requests.
- Is the blockade state shared across all app instances in a load-balanced deployment?
- This depends entirely on where the enable and disable flag lives, and the package documentation does not make that clear. If state sits in config or .env, it diverges per node and per deploy, which means one instance can serve traffic while another returns the blockade page. Confirm the storage location and how it propagates before relying on Blockade in a multi-instance setup.
- Can I apply Laravel Blockade to only some routes or route groups instead of the whole app?
- Blockade is an HTTP middleware, so it can be attached to individual route groups rather than globally, which is what most teams want so internal and admin routes stay reachable. Check the config to see whether the package's global check can be disabled in favor of explicit middleware attachment. If it only supports a global flag, plan for that limitation before deploying.
- Does Laravel Blockade return a proper 503 with Retry-After for API clients?
- The package intercepts requests and returns a maintenance response before routing, but the documentation does not confirm the exact status code, Retry-After header, or JSON content negotiation for API consumers. Test with an Accept: application/json request to see whether you get JSON or an HTML page. If your API clients need a specific contract, verify it or wrap the middleware with your own response handling.
- Does Laravel Blockade support dark mode and custom branding?
- Version 1.1.0 adds publishable CSS, a PostCSS build step, and a dark-mode illustration driven by prefers-color-scheme, so branding is more flexible than before. Confirm whether the PostCSS build runs at install time or requires a Node toolchain in your deploy pipeline, because a Node dependency in a PHP deploy is a real cost. Check that dark mode degrades gracefully when your layout does not define the relevant CSS variables. Also verify the rendered page against your actual theme rather than assuming the default looks right.
- Will php artisan blockade:install overwrite my custom views and CSS on upgrade?
- Yes, this is the main upgrade risk: the command republishes assets, and it overwrites files in public/ unless you have layered your customizations correctly. You must re-run blockade:install on upgrade to get the new 1.1.0 assets, which makes the process non-idempotent and creates a drift surface between your published directory and upstream. Decide who owns the published views and stylesheets once customized, and set up a way to detect upstream changes.
- Is romanzipp/laravel-blockade actively maintained and safe to use in production?
- The last release before 1.1.0 was in November 2020, and 1.1.0 is a largely cosmetic release after a multi-year gap, which signals the maintainer is alive but does not prove the package is tested against modern Laravel. Treat the maintenance risk as unverified rather than resolved, and note that zero dependents means nobody has audited the middleware's bypass logic. Because it sits on the availability-critical path, run your own spike and review the bypass code before shipping it.