PHPackages rasuvaeff/yii3-maintenance-mode - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. rasuvaeff/yii3-maintenance-mode ActiveLibrary[Framework](/categories/framework) rasuvaeff/yii3-maintenance-mode =============================== Maintenance mode middleware for Yii3 applications v1.0.3(3w ago)111↓87.5%BSD-3-ClausePHPPHP 8.3 - 8.5CI passing Since Jun 2Pushed 3w agoCompare [ Source](https://github.com/rasuvaeff/yii3-maintenance-mode)[ Packagist](https://packagist.org/packages/rasuvaeff/yii3-maintenance-mode)[ Docs](https://github.com/rasuvaeff/yii3-maintenance-mode)[ RSS](/packages/rasuvaeff-yii3-maintenance-mode/feed)WikiDiscussions master Synced 2w ago READMEChangelog (1)Dependencies (25)Versions (5)Used By (0) rasuvaeff/yii3-maintenance-mode =============================== [](#rasuvaeffyii3-maintenance-mode) [![Stable Version](https://camo.githubusercontent.com/a060fbcfc99c2920137258d91fb40b6ffcef8d29f361881fa5007181a9ec3f0c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7261737576616566662f796969332d6d61696e74656e616e63652d6d6f64652e7376673f6c6162656c3d737461626c65)](https://packagist.org/packages/rasuvaeff/yii3-maintenance-mode)[![Total Downloads](https://camo.githubusercontent.com/8133d1fe457e2cfb7ca6432de72806e58a80f72a034467921b5b0df347ca0647/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7261737576616566662f796969332d6d61696e74656e616e63652d6d6f64652e737667)](https://packagist.org/packages/rasuvaeff/yii3-maintenance-mode)[![Build](https://camo.githubusercontent.com/052379ee3d616e2923beba5dbcb371bffbd65b856f31599e0bac88c69b9bf01a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261737576616566662f796969332d6d61696e74656e616e63652d6d6f64652f6275696c642e796d6c3f6272616e63683d6d6173746572)](https://github.com/rasuvaeff/yii3-maintenance-mode/actions)[![Static Analysis](https://camo.githubusercontent.com/c7374d1759efe8946ad2615df64c2d6df112d1030c10e5d04d782359bf04a3b8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261737576616566662f796969332d6d61696e74656e616e63652d6d6f64652f7374617469632d616e616c797369732e796d6c3f6272616e63683d6d6173746572)](https://github.com/rasuvaeff/yii3-maintenance-mode/actions)[![Psalm Level](https://camo.githubusercontent.com/c05996788ae434d070def332e4d8bd454fc358273de444e9e0d1dcd318917340/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5073616c6d2d312d626c75652e737667)](https://github.com/rasuvaeff/yii3-maintenance-mode/actions)[![PHP](https://camo.githubusercontent.com/9d5e282cce408ea40806ddb54e9543b30a44f5a0cbccff4acf74f4e73faf9aa7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f7261737576616566662f796969332d6d61696e74656e616e63652d6d6f64652f706870)](https://packagist.org/packages/rasuvaeff/yii3-maintenance-mode)[![License](https://camo.githubusercontent.com/36d899cc7e08f18a034acefc737437f54e55cfb8b242546dada11e5c18f93988/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7261737576616566662f796969332d6d61696e74656e616e63652d6d6f64652e737667)](LICENSE.md) Maintenance mode PSR-15 middleware for Yii3. Returns HTTP 503 with `Retry-After` header. Supports IP allow-list, bypass token, JSON and HTML responses. > Using an AI coding assistant? [llms.txt](llms.txt) has a compact API reference ready to paste into context. Requirements ------------ [](#requirements) - PHP 8.3+ - `psr/http-message` ^2.0 - `psr/http-server-middleware` ^1.0 Installation ------------ [](#installation) ``` composer require rasuvaeff/yii3-maintenance-mode ``` Usage ----- [](#usage) ### 1. Add middleware to the pipeline [](#1-add-middleware-to-the-pipeline) `MaintenanceMiddleware` must be placed **as early as possible** — before routing and authentication. Otherwise requests reach the router even during maintenance. ``` // config/web.php or wherever your middleware stack is defined use Rasuvaeff\Yii3MaintenanceMode\MaintenanceMiddleware; return [ MaintenanceMiddleware::class, // ← first ErrorCatcher::class, Router::class, // ... ]; ``` ### 2. Configure in params.php [](#2-configure-in-paramsphp) ``` // config/params.php return [ 'rasuvaeff/yii3-maintenance-mode' => [ 'enabled' => false, 'retryAfter' => 300, 'allowedIps' => [], 'bypassTokenHash' => '', ], ]; ``` The package ships `config/di.php` and `config/params.php` via config-plugin. `ConfigMaintenanceProvider` and `MaintenanceMiddleware` are registered automatically. ### 3. Enable maintenance mode [](#3-enable-maintenance-mode) **Via environment variable** (no deploy required): ``` // config/params.php 'rasuvaeff/yii3-maintenance-mode' => [ 'enabled' => (bool) ($_ENV['MAINTENANCE_ENABLED'] ?? false), 'retryAfter' => 600, 'allowedIps' => ['10.0.0.1'], 'bypassTokenHash' => $_ENV['MAINTENANCE_BYPASS_HASH'] ?? '', ], ``` **Via JSON file** (toggle without deploy or restart): ``` // config/di.php — switch to FileMaintenanceProvider use Rasuvaeff\Yii3MaintenanceMode\FileMaintenanceProvider; use Rasuvaeff\Yii3MaintenanceMode\MaintenanceProvider; return [ MaintenanceProvider::class => [ 'class' => FileMaintenanceProvider::class, '__construct()' => [ 'filePath' => dirname(__DIR__) . '/maintenance.json', ], ], ]; ``` Enable: `echo '{"enabled":true,"retryAfter":600}' > maintenance.json` Disable: `rm maintenance.json` Bypass token ------------ [](#bypass-token) Generate a hash of your secret token: ``` php -r "echo hash('sha256', 'my-secret-token');" # 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 ``` Store the hash in config (never the token itself): ``` 'bypassTokenHash' => '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08', ``` Access any URL by appending `?bypass=my-secret-token`: ``` https://example.com/?bypass=my-secret-token https://example.com/admin/dashboard?bypass=my-secret-token ``` Token is compared with `hash_equals()` — timing-safe, no brute-force risk. API reference ------------- [](#api-reference) ### `MaintenanceState` [](#maintenancestate) ``` readonly class MaintenanceState { public bool $enabled = false; public int $retryAfter = 300; // seconds /** @var list */ public array $allowedIps = []; public string $bypassTokenHash = ''; // sha256 of bypass token } ``` ### `MaintenanceProvider` (interface) [](#maintenanceprovider-interface) ``` interface MaintenanceProvider { public function getState(): MaintenanceState; } ``` Implement this to create custom providers (DB, Redis, feature flag, etc.). ### `ConfigMaintenanceProvider` [](#configmaintenanceprovider) ``` $provider = new ConfigMaintenanceProvider([ 'enabled' => true, 'retryAfter' => 600, 'allowedIps' => ['127.0.0.1', '10.0.0.1'], 'bypassTokenHash' => hash('sha256', 'secret'), ]); ``` State is immutable — set once at construction. Best for config/env sources. ### `FileMaintenanceProvider` [](#filemaintenanceprovider) ``` $provider = new FileMaintenanceProvider(filePath: '/var/app/maintenance.json'); ``` Reads state on every `getState()` call — changes take effect without restart. Returns disabled state (`enabled: false`) when file is missing or invalid JSON. `maintenance.json` format: ``` { "enabled": true, "retryAfter": 600, "allowedIps": ["10.0.0.1"], "bypassTokenHash": "9f86d081..." } ``` ### `MaintenanceMiddleware` [](#maintenancemiddleware) ``` $middleware = new MaintenanceMiddleware( provider: $provider, responseFactory: $responseFactory, ); ``` Decision logic (in order): ConditionAction`enabled === false`Pass through`REMOTE_ADDR` in `allowedIps`Pass throughValid `?bypass=` tokenPass throughOtherwiseReturn 503Response format --------------- [](#response-format) ### JSON (API clients) [](#json-api-clients) Returned when `Accept: application/json` or `Accept` header is absent: ``` HTTP/1.1 503 Service Unavailable Content-Type: application/json Retry-After: 600 ``` ``` { "error": "Service Unavailable", "message": "The server is currently undergoing maintenance.", "retryAfter": 600 } ``` ### HTML (browsers) [](#html-browsers) Returned when `Accept: text/html` or any other non-JSON accept: ``` HTTP/1.1 503 Service Unavailable Content-Type: text/html; charset=utf-8 Retry-After: 600 ``` A minimal HTML maintenance page is returned. Override by implementing your own `MaintenanceProvider` wrapper or `MiddlewareInterface` decorator. Security -------- [](#security) - Bypass token compared with `hash_equals()` — timing-safe - Only the hash is stored, never the plaintext token - IP allow-list uses strict string comparison on `REMOTE_ADDR` - `FileMaintenanceProvider` catches `JsonException` gracefully — invalid file → disabled state (safe default) Examples -------- [](#examples) See [`examples/`](examples/) for detailed Yii3 wiring: providers, pipeline placement, bypass token, console command, env-based toggling. Development ----------- [](#development) ``` make install make build make cs-fix make mutation ``` License ------- [](#license) BSD-3-Clause. See [LICENSE.md](LICENSE.md). ### Health Score 43 — FairBetter than 89% of packages Maintenance95 Actively maintained with recent releases Popularity8 Limited adoption so far Community6 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~9 days Total 4 Last Release 25d ago PHP version history (2 changes)v1.0.0PHP ^8.3 v1.0.2PHP 8.3 - 8.5 ### Community Maintainers ![](https://www.gravatar.com/avatar/b0812d5572a7041dfe36e222d295b2e6dc55833a605350fcde58a51a5965ed30?d=identicon)[rasuvaeff](/maintainers/rasuvaeff) --- Top Contributors [![rasuvaeff](https://avatars.githubusercontent.com/u/1352718?v=4)](https://github.com/rasuvaeff "rasuvaeff (20 commits)") --- Tags downtimemaintenancemiddlewarephppsr-15yii3middlewaremaintenanceyii3downtime ### Code Quality TestsPHPUnit Static AnalysisPsalm, Rector Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/rasuvaeff-yii3-maintenance-mode/health.svg) ``` [![Health](https://phpackages.com/badges/rasuvaeff-yii3-maintenance-mode/health.svg)](https://phpackages.com/packages/rasuvaeff-yii3-maintenance-mode) ``` ### Alternatives [cakephp/cakephp The CakePHP framework 8.8k19.5M1.8k](/packages/cakephp-cakephp)[typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms)[typo3/cms-core TYPO3 CMS Core 3713.2M5.2k](/packages/typo3-cms-core)[tempest/framework The PHP framework that gets out of your way. 2.2k34.4k16](/packages/tempest-framework)[cakephp/authentication Authentication plugin for CakePHP 1214.1M107](/packages/cakephp-authentication)[sunrise/http-router A powerful solution as the foundation of your project. 17451.8k11](/packages/sunrise-http-router) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)