README

Maintenance mode for NimblePHP. While enabled, every request gets a 503 page except requests from allow-listed IP addresses.

Requires nimblephp/settings — the whole configuration (on/off, message, allowed IPs, retry-after) is stored there, so this module ships no migration and no table of its own.

Contents

• Module — registers the maintenance middleware, CLI commands and translations
• Maintenance — facade for toggling and configuring maintenance mode (backed by settings)
• MaintenanceMiddleware — blocks requests with a 503 page while enabled
• Commands/MaintenanceCommand — CLI commands
• Lang/ — translations (en, pl) for the maintenance page

Translations

The maintenance page title and default message are translated via the framework translation system (keys module.maintenance.title and module.maintenance.message), shipped for en and pl, and rendered in the current language. A custom message set with Maintenance::enable('...') overrides the translated default.

Installation

composer require nimblephp/maintenance

The settings module migration must have been run (it provides the storage table).

CLI

The module ships console commands (auto-registered via the module system). A fresh install needs nothing in the database — maintenance:on creates the settings rows:

php vendor/bin/nimble maintenance:on                       # enable
php vendor/bin/nimble maintenance:on --message="Back at 18:00"
php vendor/bin/nimble maintenance:allow-ip 127.0.0.1       # let yourself through
php vendor/bin/nimble maintenance:status                   # show state
php vendor/bin/nimble maintenance:disallow-ip 127.0.0.1
php vendor/bin/nimble maintenance:off                      # disable

Usage (PHP)

use NimblePHP\Maintenance\Maintenance;

// turn on (optionally with a custom message)
Maintenance::enable('Back in 10 minutes.');

// let yourself through
Maintenance::allowIp('127.0.0.1');

// status / config
Maintenance::isEnabled();        // bool
Maintenance::allowedIps();       // ['127.0.0.1', ...]
Maintenance::message();          // string
Maintenance::isAllowed($ip);     // true when off or IP allow-listed

// turn off
Maintenance::disable();

When enabled, MaintenanceMiddleware (registered at high priority) intercepts requests in beforeController: allow-listed IPs pass through, everyone else gets a 503 with a Retry-After header. The check fails open — any error while reading the state lets the request through, so a misconfiguration can't brick the site.

View / overriding the page

The page is rendered through the framework view service from the container, so whatever view module is installed renders it transparently:

• Twig module installed → Twig owns the view service, so the page is a Twig template. The module ships src/View/maintenance.twig and registers its own view directory in the Twig loader, so the default works out of the box. Custom views must be .twig.
• No Twig (base renderer) → the module ships src/View/maintenance.phtml. Custom views are .phtml under App/View.

Override the page with maintenance.view:

php vendor/bin/nimble maintenance:view test          # Twig: App/View/test.twig | base: App/View/test.phtml
php vendor/bin/nimble maintenance:view errors/down   # nested: App/View/errors/down.{twig|phtml}
php vendor/bin/nimble maintenance:view --clear       # back to the bundled default

Maintenance::setView('test');
Maintenance::clearView();

A flat name (e.g. test) maps to App/View/test.twig under Twig or App/View/test.phtml under the base renderer. Your view receives title, message, lang and retryAfter. If the view service or the view file is unavailable, a built-in 503 page is rendered as a fallback, so the module always works — even without a view module installed.

Configuration keys (in settings)

The client IP is read from REMOTE_ADDR. Behind a proxy/load balancer, make sure that reflects the real client (or add the proxy IP to the allow-list).