README

Production-grade maintenance mode for CodeIgniter 4 — typed, testable, and ready for distributed deployments.

Package

Quality

Community

Highlights

• 🛡 Timing-safe bypass — hash_equals() for every secret/cookie comparison.
• 🚦 Multiple bypass paths — IP / CIDR (IPv4 + IPv6), URL secret, signed cookie, route allow-list.
• 🗓 Scheduled windows — --start / --end, auto-deactivation on the next request.
• 📦 Pluggable storage — cache (Redis/Memcached/file via CI4 Cache) or file driver, switch with one config flag.
• 🔌 Framework events — maintenance.activated, .deactivated, .bypassed, .access_denied, .scheduled.expired.
• 🧱 JSON or HTML — content-negotiated 503 (or 302 redirect) per request.
• 🧪 149 unit tests, PHPStan + Psalm + Rector clean, PHP 8.2 / 8.3 / 8.4.

Install

composer require daycry/maintenancemode
php spark mm:publish

Then wire the filter in app/Config/Filters.php:

public array $aliases = [
    'maintenance' => \Daycry\Maintenance\Filters\Maintenance::class,
];

public array $globals = [
    'before' => ['maintenance'],
];

Quick start

# Activate (with an allow-listed IP, a secret URL bypass, and a 30 min ETA)
php spark mm:down --message "Upgrading the database" \
                  --ip "203.0.113.5" \
                  --secret "ops-token" \
                  --duration 30

# Inspect state
php spark mm:status

# Bring the site back up
php spark mm:up

# Schedule a window
php spark mm:down --start "2026-05-10 02:00" --end "2026-05-10 04:00"

# Skip 503 for healthchecks (config option)
$config->bypassRoutes = ['/health', '/api/webhooks/*'];

# Force JSON response on /api/* routes
$config->jsonRoutes = ['/api/*'];

# Render a custom view for THIS window
php spark mm:down --render errors/html/branded_503

# Redirect to a status page instead of 503
php spark mm:down --redirect https://status.example.com

Documentation

Everything else lives in docs/:

• Installation & first run
• Full configuration reference
• CLI commands
• Bypass methods & priority
• Filter & framework events
• Storage drivers (cache / file)
• Architecture
• Security model
• Troubleshooting · FAQ · Upgrade guide · Roadmap

Examples

• Basic maintenance
• Scheduled window
• JSON 503 for APIs
• Slack / PagerDuty notifications
• Multi-tenant (planned)
• Cloudflare / CDN trusted proxies (planned)

Quality bar

This package treats the toolchain as part of the contract. Every push runs:

Reproduce them locally with composer ci.

Contributing

Bug reports, feature requests and PRs are welcome. Please read CONTRIBUTING.md and the Code of Conduct first. For security issues, follow SECURITY.md — please don't file them as public issues.

License

MIT · made for the CodeIgniter 4 community.