Maintenance Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require devtia/maintenance-bundle
   

   Add the bundle to AppKernel.php (or config/bundles.php in Symfony 4+):

   new Devtia\MaintenanceBundle\MaintenanceBundle(),
   

2. Enable Maintenance Mode Update config/packages/devtia_maintenance.yaml (or config.yml in older versions):

   maintenance:
       enable_maintenance: true
   

3. First Use Case Deploy your code, and the default maintenance page will immediately activate. No additional configuration is needed for a full-site maintenance mode.

Implementation Patterns

Basic Workflow

1. Toggle Maintenance Mode Enable/disable via enable_maintenance in config. Useful for zero-downtime deployments:

   # config/packages/devtia_maintenance.yaml
   maintenance:
       enable_maintenance: true  # Set to false to exit maintenance
   

2. Route-Specific Maintenance Define regex-matched routes with custom templates:

   maintenance:
       routes_prefixes:
           - ['\/admin\/', '%kernel.project_dir%/templates/maintenance/admin.html.twig']
           - ['\/api\/', '@Maintenance/custom_api.html.twig']
   

   • Pattern: Use PHP regex (e.g., \/admin\/.* for all admin routes).
   • Template Paths: Supports Twig paths (@Bundle/) or absolute paths.

3. Dynamic Configuration Override settings per environment (e.g., config/packages/devtia_maintenance_dev.yaml):

   maintenance:
       enable_maintenance: false  # Disable in dev
   

4. Integration with Deploy Scripts Automate toggling via CI/CD:

   # Before deploy
   sed -i 's/enable_maintenance: false/enable_maintenance: true/' config/packages/devtia_maintenance.yaml
   git add config/packages/devtia_maintenance.yaml
   git commit -m "Enable maintenance mode"
   

Gotchas and Tips

Pitfalls

1. Regex Edge Cases

   • Forgetting to omit leading/trailing slashes in route patterns (e.g., admin/ → \/admin\/).
   • Overlapping routes may cause unexpected behavior (e.g., \/api\/ and \/api\/v1\/).
   • Fix: Test regex patterns with preg_match() in a twig shell or php artisan tinker.

2. Template Caching

   • Twig templates for maintenance pages are not auto-cached by default. Clear cache after changes:

     php bin/console cache:clear
     

3. Symfony 4+ Compatibility

   • The bundle targets older Symfony versions (last release: 2020). For Symfony 5/6:
     • Manually register the bundle in config/bundles.php (not AppKernel).
     • Use config/packages/devtia_maintenance.yaml instead of config.yml.

4. HTTP Caching Headers

   • The bundle does not set 503 Service Unavailable headers. Add middleware for stricter behavior:

     // src/EventListener/MaintenanceListener.php
     public function onKernelRequest(GetResponseEvent $event) {
         if ($this->maintenanceEnabled) {
             $event->setResponse(new Response('', 503));
         }
     }
     

Tips

1. Custom Templates Extend the default template by copying vendor/devtia/maintenance-bundle/src/Resources/views/Maintenance/default.html.twig to your project (e.g., templates/maintenance/custom.html.twig).

2. Environment Variables Use .env for dynamic toggling:

   # config/packages/devtia_maintenance.yaml
   maintenance:
       enable_maintenance: '%env(bool:MAINTENANCE_MODE)%'
   

   Then set MAINTENANCE_MODE=true in your environment.

3. Logging Maintenance Events Add a listener to log when maintenance is enabled/disabled:

   // src/EventListener/MaintenanceLogger.php
   public function onKernelRequest(GetResponseEvent $event) {
       if ($this->maintenanceEnabled) {
           \Log::info('Maintenance mode activated');
       }
   }
   

4. Whitelisting IPs Combine with firewall rules to allow specific IPs (e.g., your team’s IPs) to bypass maintenance:

   # config/packages/security.yaml
   firewalls:
       main:
           ip: 192.168.1.0/24  # Allow your office subnet
   

5. Testing Mock the bundle in tests by overriding the MaintenanceChecker service:

   $container->set('devtia_maintenance.maintenance_checker', $this->createMock(MaintenanceChecker::class));