romanzipp/laravel-blockade
romanzipp/laravel-blockade gives your Laravel app a simple way to block incoming access—ideal for maintenance windows, restricting specific IPs, or temporarily locking down routes via configurable middleware rules.
romanzipp/laravel-blockade is a small middleware-plus-view package for putting a Laravel app behind a maintenance/WIP page without using php artisan down. Treat it as a thin wrapper around a config flag, a middleware check, and a Blade view—not a full maintenance-mode system.
As of 1.1.0 the package ships prebuilt CSS/SVG assets and an installer command, so the setup flow has changed: php artisan blockade:install is now the primary entry point rather than vendor:publish.
Start by verifying compatibility, because the package has historically had long gaps between releases and no dependents:
composer show romanzipp/laravel-blockade --all
Check its illuminate/* constraints against your Laravel version before committing. Pin an exact version and test on a branch. Note that 1.1.0 is a maintenance/assets release—it does not announce new framework constraints, so do not assume Laravel 11 support from it.
Minimal install:
composer require romanzipp/laravel-blockade
php artisan blockade:install
blockade:install publishes the config, views, and the new CSS/asset files. If you already published views in an earlier version, decide deliberately whether to overwrite them (see gotchas). Confirm the provider namespace from the package's composer.json; auto-discovery likely registers it, so you may not need --provider.
Then register the middleware in app/Http/Kernel.php, either in the web group or a dedicated group:
protected $middlewareGroups = [
'web' => [
// ...
\RomanZipp\Blockade\Http\Middleware\Blockade::class,
],
];
Where to look first: the middleware class—it decides whether to short-circuit the request and what response/view to return. Then read config/blockade.php for the enable flag and bypass options, the published Blade view for the page, and the newly published assets directory (typically public/vendor/blockade/) to confirm the CSS and dark-mode SVG actually landed. php artisan blockade:install --help and the command class are now the most reliable source of truth for available artisan commands.
First use case: a scheduled maintenance window for a small internal app. Enable the blockade, confirm affected routes return a 503 with your page, confirm an allowlisted IP or secret token still reaches the app, toggle your OS/browser to dark mode and confirm the page renders correctly, then disable it. If you cannot verify a bypass path, do not enable it in production.
Scope the middleware deliberately. Adding it to the global web group blocks all browser traffic. If API consumers should keep working, apply it only to selected route groups:
Route::middleware('blockade')->group(function () {
// public UI routes
});
Drive the toggle from environment or config. Keep staging in WIP mode while production stays open:
// config/blockade.php
'enabled' => env('BLOCKADE_ENABLED', false),
Remember that config:cache freezes this value; see the gotchas below.
Toggle from deploy scripts. The existence of blockade:install confirms the package ships artisan commands, so an enable/disable pair is likely available—but verify the exact names against the command classes rather than trusting the README. Always wrap the pair so a failed deploy cannot leave the site blocked:
php artisan blockade:enable # confirm exact command in the package
php artisan migrate --force
php artisan blockade:disable
If the commands you need are missing, call the facade or flip the config value from a small artisan command you own.
Re-run the installer as part of your upgrade step, not your deploy step. Add php artisan blockade:install to the post-composer update checklist for this package (or a one-off deploy task guarded so it only runs when the package version changes). Re-running it on every deploy risks clobbering view/config customizations.
Use a bypass for stakeholders. A secret query parameter, header, or IP allowlist lets QA and clients preview the app during a WIP period. Keep the secret in .env, not in the repo, and rotate it after each window. Verify the bypass check runs after session/auth middleware if it depends on the authenticated user.
Customize the page, but keep it static. Publish and edit the Blade view to include status, ETA, and a contact link. The 1.1.0 assets give you a styled page with a dark-mode illustration for free—extend the stylesheet via the published CSS rather than inlining styles in the Blade view, so the prefers-color-scheme rules keep working. Avoid database queries or service calls in the view—it renders precisely when the app may be degraded. Serve a cached/static HTML fragment if possible.
Test both colour schemes. Add a note to your QA checklist (or a Playwright/Dusk assertion on the prefers-color-scheme media query) that the page is legible in light and dark mode; the illustration is a separate dark-mode SVG, so a missing asset shows up only in dark mode.
Schedule windows. Put enable/disable in a scheduled command or your deploy pipeline, and add a feature test that asserts a 503 with the expected view when enabled and a 200 when disabled or bypassed.
Do not run this alongside php artisan down. Laravel's down mode short-circuits earlier in the HTTP kernel, so the blockade page may never render. Pick one owner of maintenance state per environment.
php artisan blockade:install after composer update, otherwise the Blade view may reference CSS/SVG that was never published and the page renders unstyled (or the dark-mode illustration 404s). Follow it with php artisan view:clear.public/, so it is cached by browsers and reverse proxies. After an asset-affecting upgrade, bust it—Laravel Mix/Vite hashing won't apply here—and make sure your deploy copies public/vendor/blockade/ to the web root. On read-only or containerised filesystems, verify the installer can actually write there.503 with a Retry-After header so uptime monitors and search engines behave correctly. Check what the package returns and customize the response if needed.StartSession or SubstituteBindings, bypass logic tied to auth or route models will not work. If it runs too late, some routes may execute queries before being blocked. Test the exact position in your kernel.config:cache freezes the toggle. Toggling BLOCKADE_ENABLED in .env at runtime has no effect after caching. Toggle via a file, database row, or cache key instead, or re-run config:cache as part of the deploy.illuminate/* constraints yourself; for anything customer-facing, weigh php artisan down with a custom resources/views/errors/503.blade.php, or fork/vendor the middleware and own it.config:cache, confirm blockade:install was run on the current deploy (check public/vendor/blockade/ exists), check route exclusions, and check whether another middleware or down mode intercepts first. Log the resolved enable flag at boot in local.How can I help you explore Laravel packages today?