Download the PHP package rasuvaeff/yii3-maintenance-mode without Composer

rasuvaeff/yii3-maintenance-mode

Русская версия

Production-oriented PSR-15 maintenance middleware for Yii3. It returns HTTP 503 with Retry-After, supports safe header bypass, health-path exclusions, IPv4/IPv6 CIDR allow-lists, trusted proxies, atomic file switching, and custom responses.

Using an AI coding assistant? llms.txt contains a compact API reference ready to paste into context.

Requirements

• PHP 8.3-8.5
• ext-filter
• PSR-7 HTTP messages and PSR-17 response factory
• PSR-15 middleware and request handler
• Yii config-plugin in the root application for automatic Yii3 DI registration

Installation

Usage

Middleware order

Place maintenance mode before routing and authentication, but inside global error handling, request ID, observability, CORS, and security middleware. This keeps 503 responses observable and ensures middleware failures are caught.

Configuration provider

The package registers ConfigMaintenanceProvider and MaintenanceMiddleware through Yii config-plugin.

ConfigMaintenanceProvider captures immutable state when the container creates it. Use FileMaintenanceProvider when state must change without rebuilding the container.

config/di.php and config/params.php are merged automatically only when the root application uses the yiisoft/config plugin (yiisoft/app, yiisoft/app-api). Without it, wire the services by hand:

Atomic file switching

Use the installed command instead of shell redirection or deleting the file. It writes a complete temporary file and atomically renames it.

Bind the file provider in application DI:

FileMaintenanceProvider accepts strict JSON types. Missing, unreadable, malformed, or schema-invalid files currently produce disabled state. This is a legacy fail-open policy; use the atomic writer and monitor file errors rather than relying on partial manual writes.

Bypass token

Generate a high-entropy token and its SHA-256 hash:

For the literal token my-secret-token, the correct hash is:

Store only the hash and send the plaintext token over TLS in a header:

The comparison uses hash_equals(). This protects against timing attacks, not weak-token brute force. The legacy ?bypass= query parameter remains enabled for backward compatibility, but URLs may leak through logs, browser history, analytics, and referrers. Disable it in new deployments.

Health paths, CIDR, and proxies

allowedIps accepts exact IPv4/IPv6 addresses and CIDR rules. The default IP resolver only accepts a valid REMOTE_ADDR.

Exclude health endpoints and resolve forwarded client addresses only from explicitly trusted proxies:

Never trust X-Forwarded-For without a trusted-proxy allow-list.

Custom response

Implement MaintenanceResponseFactory and inject it into MaintenanceMiddleware to provide branded HTML, RFC 9457 problem details, localization, or additional headers.

The default factory returns:

• HTTP 503;
• Retry-After;
• Cache-Control: no-store;
• JSON for absent Accept, application/json, and application/*+json;
• HTML when text/html has the higher quality value.

API reference

Security

• Keep bypass tokens random, secret, and TLS-only.
• Prefer X-Maintenance-Bypass; disable query bypass in new deployments.
• Never log the plaintext bypass header.
• Configure trusted proxies explicitly before reading forwarded headers.
• Keep health exclusions narrow and unauthenticated-data-free.
• Use the atomic writer; do not update JSON with echo > file.
• Invalid file state is fail-open for backward compatibility and should be monitored.

Examples

See examples/ for executable config and file-provider examples.

Development

License

BSD-3-Clause. See LICENSE.md.