Statamic Maintenance Mode Laravel Package

Getting Started

wahlemedia/statamic-maintenance-mode is a Statamic addon that replaces Laravel's blunt php artisan down with a controllable 503 gate: CP-driven toggle, scheduled windows, IP/user exemptions and a customisable holding page. Day one looks like this:

composer require wahlemedia/statamic-maintenance-mode
php artisan vendor:publish --tag="statamic-maintenance-mode-config"
php artisan vendor:publish --tag="statamic-maintenance-mode-views"

• Look here first: the published config file (config/statamic-maintenance-mode.php) — that is where exemptions, schedule and the bypass token live. Second, the published view under resources/views/vendor/statamic-maintenance-mode/ so you can brand the holding page with your site's Antlers layout instead of shipping the default.
• Where you flip it: the control panel (a utility/nav entry added by the addon's service provider) for humans, and the package's own artisan commands for CI/deploy scripts. Don't assume php artisan down behaves the same — use the addon's commands so the state stays in sync with what the CP shows.
• First use case: a deployment window on a production Statamic site where the client must still be able to log into /cp and preview the site while editors see the maintenance page. Whitelist your office IP plus the client's, set a start/end window, and set the secret bypass token so you can smoke-test as an anonymous visitor without touching the whitelist.

Version note: this is v2.0.2, a patch on the v2.0 line (Statamic 4/5, Laravel 10/11, PHP 8.1+). The release notes are an auto-generated compare link only, so read the v2.0.1...v2.0.2 diff before upgrading — treat it as a low-risk bugfix drop, but confirm nothing touched config keys you depend on.

Implementation Patterns

Scheduled windows over ad-hoc toggling. Rather than turning maintenance on manually at 02:00, configure the window in the CP/config and let the scheduler drive it. This requires php artisan schedule:run to actually be running in cron (or schedule:work in a container) — otherwise the window silently never opens or, worse, never closes.

CI/CD gate. Wrap deploys so the site goes down before composer install/migrations and comes back up on success and on failure:

php artisan maintenance:on || true
trap 'php artisan maintenance:off' EXIT
./deploy.sh

Always trap the "off" — a failed pipeline that leaves the site in maintenance is the classic outage.

Bypass token for QA and client review. Generate a long random token, store it in .env, and hand out https://site.test/?secret=<token> links. This lets stakeholders preview the live site during a freeze without you maintaining an IP allowlist. Rotate it after each window.

Middleware-level exemptions for machine traffic. Health checks, uptime monitors, webhook endpoints and the Statamic REST/GraphQL API will all get a 503 unless exempted. Decide deliberately: usually you want /cp, health endpoints and your payment/webhook routes reachable, and public content blocked.

Custom holding page. Publish the view and extend your real layout so the 503 page keeps fonts, logo and analytics-free styling. Include an <meta http-equiv="refresh"> or at least a human-readable "back at HH:MM" line — the addon returns a Retry-After header, so mirror that timestamp in the copy.

Pair with a status page, not a support inbox. The holding page is the only thing visitors see; give it one clear link out.

Gotchas and Tips

• Static caching wins. Statamic's static cache / full-page cache can serve already-generated HTML before Laravel middleware ever runs, so the maintenance page never appears. Clear the static cache as part of enabling maintenance, and consider disabling static caching for the window.
• IP detection behind a proxy or CDN. Whitelisting by IP fails silently on Cloudflare/ALB unless TrustProxies is configured and the correct forwarded header is trusted. Test the whitelist from outside your network, not from localhost.
• Scheduler dependence. Scheduled windows are only as reliable as your cron. Add a monitor that alerts if the site has been in maintenance longer than the configured end time.
• Secret tokens leak. Query-string tokens end up in access logs, Referer headers and screenshots. Prefer short-lived tokens, rotate after each window, and don't reuse the one from the docs.
• Multi-site behaviour. On a multi-site install, confirm whether the toggle is global or per-site before you promise a client that "only the UK store goes down." Verify against the actual config keys rather than assuming.
• Local vs production. Set the config so maintenance is never accidentally enabled in local/testing; a leftover state file committed or a stray .env flag will confuse the next developer.
• Extension points: the published config for exemptions/schedule, the published view for presentation, and the service provider for registering your own exemption logic (e.g. allow any authenticated CP user, or allow requests carrying a specific header from your load balancer's health checker).
• Upgrade hygiene on the v2 line: pin ^2.0, and after each patch bump re-run vendor:publish --force only for views you have actually customised — republishing config will overwrite your allowlist.