Maintenance Mode Bundle

⭐ Found this useful? Install from Packagist · Give it a star on GitHub so more developers can find it.

Maintenance Mode Bundle — Put a Symfony site into maintenance mode (HTTP 503) with configurable exclusions, a Twig admin panel, scheduled windows, append-only history, and pluggable storage / access gates. Tested on Symfony 7.4, 8.0, and 8.1 · PHP 8.2+ (Symfony 8.x requires PHP 8.4+).

This bundle is FrankenPHP worker mode friendly.

Features

• 503 listener — Configurable-priority kernel.request interceptor (default after router), HTML or JSON, dynamic Retry-After, Cache-Control: no-store.
• Exclusions — Exact paths, prefixes, route names, globs, #regex# / ~regex~, IPs/CIDR, #[ExcludeFromMaintenance], soft bypass token.
• Admin panel — Enable / disable / schedule / clear schedule / history under a configurable prefix (default /_maintenance).
• CLI — enable / disable / status / hash-password for deploys and ops scripts.
• Events & Twig — Domain events on state changes; nowo_maintenance_is_enabled() / nowo_maintenance_state().
• Password gate — Optional password_hash (bcrypt / argon2id); replaceable via MaintenanceAccessGateInterface.
• Pluggable storage — Filesystem JSON/JSONL by default; swap for Doctrine or anything else via DI.

Installation

composer require nowo-tech/maintenance-mode-bundle

With Symfony Flex, the recipe registers the bundle and adds config. Without Flex, see docs/INSTALLATION.md.

# config/routes.yaml
nowo_maintenance_mode:
    resource: '@NowoMaintenanceModeBundle/Resources/config/routes.yaml'

Requirements

• PHP >=8.2 (<8.6); Symfony 8.0 and 8.1 require PHP 8.4+
• Symfony 7.4, 8.0, or 8.1 (^7.4 || ^8.0)
• Twig for the maintenance page and panel templates

Configuration

nowo_maintenance_mode:
    enabled: true
    default_message: "We're making a few gentle improvements. Everything you care about is safe."
    panel:
        path_prefix: '/_maintenance'
    security:
        password_protection: true
        password_hash: '%env(MAINTENANCE_PASSWORD_HASH)%'
        access_roles: [ROLE_ADMIN]
        # allow_unauthenticated: false
    exclusions:
        paths: ['/health']
        path_prefixes: ['/api/health']

Usage

Open /_maintenance to toggle maintenance. Visitors hit the public page with HTTP 503; excluded routes and the panel keep working. In dev, preview the configured page at /_maintenance_preview (like /_error/503). Demo gallery: /examples.

$maintenance->enable('Deploy in progress', 'ops');
$maintenance->disable('ops');

See docs/USAGE.md.

Demo

Demo	Symfony	PHP	Default port
demo/symfony8	8.1	8.5	8055

Runs FrankenPHP + Caddy (FRANKENPHP_MODE=worker by default). Panel password: maintenance. See docs/DEMO-FRANKENPHP.md.

make -C demo help
make -C demo up-symfony8

Development

make up
make install
make test
make cs-check
make phpstan
make release-check

Documentation

• Installation
• Configuration
• Usage
• Contributing
• Code of Conduct
• Changelog
• Upgrading
• Release
• Security
• Engram
• Spec-driven development
• GitHub Spec Kit

Additional documentation

• Demo (FrankenPHP)
• Maintenance page examples
• GitHub Actions CI requirements

Tests and coverage

• Tests: PHPUnit (PHP)
• PHP: 100% Lines (run make coverage-check)

License and author

MIT · Nowo.tech · Héctor Franco Aceituno