Laravel Maintenance Mode: Custom Pages

Tip: Enable Maintenance Mode

php artisan down

Returns 503 for all requests.

Gotcha: Bypass with Secret

php artisan down --secret=my-secret

Visit /my-secret to get a bypass cookie. Useful for testing during maintenance.

Tip: Custom Maintenance View

{{-- resources/views/errors/503.blade.php --}}

Laravel renders this view during maintenance.

Gotcha: Allow Specific IPs

php artisan down --allow=127.0.0.1 --allow=192.168.1.0/24

These IPs bypass maintenance mode.

Tip: Retry-After Header

php artisan down --retry=60

Tells clients to retry after 60 seconds.

Gotcha: Queue Workers During Maintenance

Queue workers continue running during maintenance mode. Only HTTP requests are affected.

Tip: Use route:cache Carefully

php artisan route:cache is fast, but it doesn't work with closure-based routes. Every time you cache routes, Laravel serializes them. If you have Route::redirect() or closure callbacks, the cache breaks. Stick to controller-based routes in production.

Tip: Model APP_KEY Rotation

Rotating APP_KEY invalidates all encrypted data — cookies, encrypted DB columns, and password reset tokens. If you must rotate (e.g., after a leak), plan a migration that re-encrypts existing data with the new key.

Gotcha: Local Scope Leaks

Global scopes defined in booted() apply to ALL queries on that model — including relationships. An innocent User::all() in admin panel might exclude soft-deleted users if a global scope is active.

Senior Insight

Maintenance mode is one of those features you don't think about until you need it urgently. Laravel's default maintenance page is functional but ugly — I always customize it with the company branding, an estimated return time, and a status page link. Also, use php artisan down --redirect=/maintenance instead of showing the raw error page. And test your maintenance mode flow in staging; I've seen php artisan up fail because of file permissions on the framework/down file.

Source: Laravel News (https://laravel-news.com/), Freek.dev (https://freek.dev/tags/laravel), Spatie Blog (https://spatie.be/blog)