bretrzaun/maintenance-bundle

Bundle for maintenance switch in Symfony applications

0.5.0 2025-10-14 21:00 UTC

Requires

• php: >=8.1
• symfony/yaml: ^6.0||^7.0
• twig/twig: ^3.0

Requires (Dev)

• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^10.5
• rector/rector: ^2.0
• symfony/asset: ^6.0||^7.0
• symfony/browser-kit: ^6.0||^7.0
• symfony/framework-bundle: ^6.0||^7.0
• symfony/phpunit-bridge: ^7.0
• symfony/translation: ^6.0||^7.0
• symfony/twig-bundle: ^6.0||^7.0
• symfony/var-dumper: ^6.0||^7.0

MIT

• Bret R. Zaun

README

Installation

composer require bretrzaun/maintenance-bundle

Register bundle in config/bundles.php:

\BretRZaun\MaintenanceBundle\MaintenanceBundle::class => ['all' => true]

Configuration

Create the following configuration file

# config/packages/maintenance.yaml
maintenance:
    enabled: false
    template: 'maintenance.html.twig'

    # Maintenance window start
    from: 2018-12-01 00:00:00

    # Maintenance window end
    until: 2018-12-03 00:00:00
    
    # IP addresses allowed to access during maintenance
    # Supports:
    # - Wildcards: 10.*.*.* or 192.168.*.*
    # - CIDR notation: 192.168.1.0/24
    # - IPv6: 2001:db8::/32
    # - Exact IPs: 192.168.1.1
    allowed_ip:
      - '10.*.*.*'           # All 10.x.x.x IPs
      - '192.168.1.0/24'     # Entire /24 network
      - '2001:db8::/32'      # IPv6 network
      - '203.0.113.42'       # Single IP

Options

• enabled: if set to true manually activates the maintenance mode
• template: template to render, when maintenance mode is activated
• from: begin maintenance mode at the given date/time (only when 'enabled' is false)
• until: end maintenance mode at the given date/time (only when 'enabled' is false)
• allowed_ip: list of IP addresses who can access the application even in maintenance mode

Template

The bundle has a default maintenance template (see src/Resources/views/maintenance.html.twig).

You can use your own template (see configuration). In case your maintenance template extends from a parent layout you might want to exclude certain parts while in maintenance (e.g. a menu). This can be done with like so:

    {% if not maintenance_mode() %}
        ...
    {% endif %}

If the option "allowed_ip" is used, certain users can access the application even it is in maintenance mode. To make these users aware of this you can add the following to the layout template:

{% if maintenance_mode_allowed() %}
    <div class="alert alert-warning">Maintenance mode is activated!</div>
{% endif %}