skip to content

In Laravel 13, what does php artisan down do to incoming requests, and how do --secret and --with-secret let the team keep using the site?

level: juniorimportance: must knowfreq 55%

answer

  1. 503 for every request by default
  2. payload stored in storage/framework/down
  3. visit /{secret} once
  4. laravel_maintenance cookie, 12 hours
  5. php artisan up removes it

basics

~20 s

php artisan down makes Laravel answer requests with a 503 maintenance response. With --secret=token (or a random --with-secret), visiting /token sets a signed laravel_maintenance bypass cookie so that browser uses the site normally; php artisan up ends maintenance.

solid answer

~40 s

`php artisan down` activates the maintenance driver (by default it writes a JSON payload to `storage/framework/down`) and writes `storage/framework/maintenance.php`. From then on the maintenance middleware in the default stack answers requests with a 503 (the `--status` option can change it). `--secret="..."` stores a bypass token in that payload, and `--with-secret` generates a random one and prints the bypass URL. Visiting `https://site/<secret>` redirects to `/` and sets a `laravel_maintenance` cookie, valid for 12 hours and signed with an HMAC of the secret, so that browser sees the real application while everyone else gets the maintenance page. `php artisan up` deactivates the driver and deletes `maintenance.php`. Running `down` again while down just updates the options.

code

bash · 8 lines
bash
# start the migration window, generating a bypass token
php artisan down --with-secret

# engineers open APP_URL/<printed-secret> once to get the bypass cookie
php artisan migrate --force

# reopen the site
php artisan up

go deeper

for a junior

Recall that php artisan down returns 503 to everyone, --secret or --with-secret gives a bypass URL, and php artisan up ends it.

for a middle

Explain what down writes to storage/framework, how the secret URL issues a signed laravel_maintenance cookie, and how long it lasts.

for a senior

Plan the window: who gets the secret, how to rotate it by re-running down, and what else pauses, such as queue workers.

for a principal

Weigh maintenance windows against zero-downtime releases and decide which changes, like table rewrites, justify taking the site down.

## The scenario A streaming-subscription site needs a short window to run a database migration that rewrites the `subscriptions` table. The team wants subscribers to see a friendly "back soon" page, while the on-call engineers can still log in and check that plans, renewals and playback pages work before reopening. ## What `php artisan down` does `Illuminate\Foundation\Console\DownCommand` performs a few steps: 1. builds a **payload** from its options: excluded paths, `redirect`, `retry`, `refresh`, `secret`, `status` (default `503`) and an optional prerendered `template`; 2. calls the maintenance driver's `activate()`; the default **file** driver writes that payload as JSON to `storage/framework/down`; 3. copies a small stub to `storage/framework/maintenance.php`, which `public/index.php` checks before anything else loads; 4. dispatches a `MaintenanceModeEnabled` event and prints the bypass URL when a secret is set. On each request, the maintenance middleware in the default stack sees that maintenance mode is active and stops the request with a 503, unless the path is excluded (the health route is excluded automatically) or the visitor holds a valid bypass cookie. ## Bypassing with a secret ```bash php artisan down --secret="night-migration-7f3a" # or let Laravel generate one php artisan down --with-secret ``` - `--secret` stores the token you give it. Keep it to letters, digits and dashes; characters such as `?` or `&` have meaning in URLs. - `--with-secret` generates a random string and prints `You may bypass maintenance mode via [APP_URL/<secret>]`. The engineer opens `https://example.com/night-migration-7f3a`. The middleware compares the path with the stored secret using a timing-safe `hash_equals`, then: - redirects to the intended URL, falling back to `/`; - attaches a `laravel_maintenance` cookie whose value holds an expiry timestamp **12 hours** ahead and an HMAC-SHA256 of that timestamp keyed with the secret; - uses the session configuration's path and domain for the cookie. On later requests the cookie is checked: the MAC must match and the expiry must be in the future. Because the MAC is keyed with the secret, running `down` again with a different secret invalidates every cookie issued for the old one. ## Ending maintenance ```bash php artisan up ``` `UpCommand` calls the driver's `deactivate()` (the file driver deletes `storage/framework/down`), deletes `storage/framework/maintenance.php` and dispatches `MaintenanceModeDisabled`. If the app was not down it prints "Application is already up." ## Planning the window 1. Announce the window to subscribers ahead of time. 2. Run `php artisan down --with-secret` and share the printed URL only with the engineers on call. 3. Each engineer opens the secret URL once and confirms they see the real app. 4. Run the migration and any data fixes. 5. Verify renewals, plan pages and playback through the bypass cookie. 6. Run `php artisan up` and watch error rates. While the app is down, queue workers stop taking jobs and scheduled tasks are skipped unless they are explicitly marked to run in maintenance, so renewal jobs queued during the window run afterwards. ## Useful details | Behaviour | What happens | |---|---| | `down` while already down | payload is replaced; output says "Maintenance mode options updated." | | Status code | `503` unless `--status` is given | | Bypass cookie lifetime | 12 hours from the visit to the secret URL | | Health route | stays reachable during maintenance | | Queued jobs | workers pause processing while the app is down | ## What a good answer avoids - Treating the secret as authentication. It only lifts the maintenance gate; the application's own login and authorization still apply. - Sharing the secret URL widely. Anyone who has it gets a 12-hour bypass cookie. - Forgetting `php artisan up`. The file stays until someone removes it, and the site stays down.

  • An engineer shared the Laravel maintenance bypass URL in a public channel by mistake; how do you revoke access without ending maintenance?
    Run `php artisan down` again with a new `--secret` or `--with-secret`. Re-running `down` while down replaces the payload, and the bypass cookie's MAC is keyed with the secret, so cookies issued for the old token no longer validate. Engineers then visit the new secret URL.
  • Does holding the Laravel maintenance bypass cookie log an engineer in?
    No. The cookie only makes the maintenance middleware let the request through; the application then treats the visitor like any other, so login, sessions and authorization work exactly as normal.

A shop door with a "closed for stocktaking" sign: customers turn away, but staff who know the code get a wristband at the side door that lets them walk in and out for the rest of the shift.

saying these in an interview costs you the question

  • php artisan down stops the web server process
  • The secret URL logs the visitor in as an administrator
  • The bypass cookie lasts until php artisan up runs
  • Changing the secret leaves old bypass cookies valid
  • Maintenance mode returns 500 by default