contenir/maintenance-laminas-mvc

Laminas MVC adapter for contenir/maintenance — short-circuits dispatch with 503 when maintenance mode is active.

v0.2.0 2026-05-08 06:08 UTC

Requires

• php: ^8.1 || ^8.2 || ^8.3
• contenir/maintenance: ^0.1.0
• laminas/laminas-eventmanager: ^3.0
• laminas/laminas-http: ^2.0
• laminas/laminas-mvc: ^3.4
• laminas/laminas-servicemanager: ^3.0

Requires (Dev)

• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^3.10

MIT

README

Laminas MVC adapter for contenir/maintenance.

When the admin (Contenir CMS) toggles maintenance mode, this adapter short-circuits dispatch in the consuming Site with a 503 response — until the flag is cleared.

Install

composer require contenir/maintenance-laminas-mvc

Wire-up

1. Register the module

// config/modules.config.php
return [
    // ...other modules
    'Contenir\\Maintenance\\Laminas\\Mvc',
];

If you have laminas/laminas-component-installer installed, this happens automatically.

2. Point at the shared state file

// config/autoload/maintenance.local.php
return [
    'maintenance' => [
        // Same path the admin (Contenir CMS) is configured to write.
        'file' => '/var/www/shared/maintenance.local.php',
    ],
];

That's the minimum. With nothing else set, the adapter will return a plain 503 page with the configured message whenever maintenance is active.

3. (Optional) Bypass for operators

// config/autoload/maintenance.local.php
return [
    'maintenance' => [
        'file'   => '/var/www/shared/maintenance.local.php',
        'bypass' => static function (\Laminas\Mvc\MvcEvent $event): bool {
            // Return true to let the request through despite maintenance mode.
            // E.g. allow authenticated super-admins:
            $auth = $event->getApplication()->getServiceManager()->get('auth');
            return $auth->hasIdentity() && $auth->getIdentity()->isSuperAdmin();
        },
    ],
];

4. (Optional) Customise the response body

'maintenance' => [
    'body_template' => file_get_contents(__DIR__ . '/../templates/maintenance.html'),
    'retry_after'   => 1800, // seconds, sent as Retry-After header
],

body_template is a sprintf format string with a single %s for the escaped message text. If you need anything more elaborate (full layout, view helpers, translation), replace the MaintenanceListener service with your own factory.

Listener priority

The listener attaches at MvcEvent::EVENT_DISPATCH priority 10000 so it runs before route → controller dispatch and before any other listener that hasn't asked for higher priority. The exact value is exposed as Module::DISPATCH_PRIORITY if you need to coordinate with another listener.