Symfony Maintenance Mode Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require drawik/symfony-maintenance-mode-bundle
   

   Ensure your project uses Symfony 6 or 7.

2. Enable Maintenance Mode:

   php bin/console maintenance:enable
   

   This immediately locks the application (default lock file: /tmp/maintenance_mode.lock).

3. First Use Case:

   • Trigger maintenance during deployments to prevent user access.
   • Test locally by whitelisting your IP in config/packages/maintenance_mode.yaml:

     maintenance_mode:
         maintenance_config:
             allowed_ips: ['127.0.0.1', '::1']
     

Implementation Patterns

Workflows

1. Deployment Integration:

   • Use the bundle in a post-deploy hook (e.g., GitHub Actions, Deployer):

     php bin/console maintenance:enable
     # Run migrations/deployments...
     php bin/console maintenance:disable
     

   • For zero-downtime deployments, enable maintenance before pushing new code.

2. Environment-Specific Config:

   • Override maintenance_mode.yaml per environment (e.g., config/packages/dev/maintenance_mode.yaml):

     # config/packages/prod/maintenance_mode.yaml
     maintenance_mode:
         maintenance_config:
             enabled: 0  # Disabled in production by default
             allowed_ips: ['192.168.1.100']  # Only allow staging server
     

3. Dynamic IP Whitelisting:

   • Fetch allowed IPs from an API or database during runtime by extending the bundle (see Extension Points).

4. Custom Lock File:

   • Store the lock file in a project directory (e.g., var/maintenance.lock) for better portability:

     maintenance_mode:
         maintenance_config:
             lock_file_path: '%kernel.project_dir%/var/maintenance.lock'
     

Integration Tips

• Symfony Flex: The bundle auto-registers; no manual bundles.php changes are needed.
• HTTP Middleware: The bundle adds a MaintenanceModeListener to Symfony’s event dispatcher. Override its logic (e.g., MaintenanceModeListener::onKernelRequest) if you need custom logic (e.g., API vs. web maintenance).
• Testing: Mock the listener in PHPUnit to test maintenance mode behavior:

  $kernel->getContainer()->get('maintenance_mode.listener')->setEnabled(true);
  

Gotchas and Tips

Pitfalls

1. Lock File Permissions:

   • Ensure the lock file (/tmp/maintenance_mode.lock by default) is writable by the web server user (e.g., www-data).
   • Fix: Set permissions explicitly:

     chmod 666 /tmp/maintenance_mode.lock
     

   • Better: Use a project-specific path (e.g., var/maintenance.lock) with chmod 644.

2. Caching Issues:

   • If using Symfony’s HTTP cache (e.g., HttpCache), clear it after disabling maintenance:

     php bin/console cache:clear
     

   • The bundle does not clear caches automatically.

3. IP Whitelisting Quirks:

   • The allowed_ips config supports both IPv4 and IPv6, but subnet masks (e.g., 192.168.1.0/24) are not supported.
   • Workaround: Use a wildcard (e.g., 192.168.1.*) or extend the bundle to parse CIDR notation.

4. Symfony Debug Mode:

   • Maintenance mode ignores Symfony’s APP_DEBUG setting. Debug mode does not bypass maintenance.

5. Console Commands in Maintenance:

   • The maintenance:enable/disable commands themselves are not blocked by maintenance mode. Use this to your advantage for emergency fixes:

     php bin/console maintenance:disable --env=prod  # Works even if maintenance is on
     

Debugging

1. Check Lock File:

   • Verify the lock file exists and contains 1 (enabled) or 0 (disabled):

     cat /tmp/maintenance_mode.lock
     

   • If empty, the bundle failed to write it (check permissions).

2. Log Listener Errors:

   • Enable Symfony’s debug mode to see if the MaintenanceModeListener throws exceptions:

     APP_ENV=dev APP_DEBUG=1 php bin/console server:run
     

3. Test IP Whitelisting:

   • Use curl to test if your IP is allowed:

     curl -I http://localhost
     

   • Expected: 503 Service Unavailable (unless whitelisted).

Extension Points

1. Custom Maintenance Page:

   • Override the default 503 page by creating a custom twig template at templates/bundles/MaintenanceMode/error503.html.twig.
   • Pass dynamic data via the listener’s onKernelException event.

2. Dynamic IP Allowlist:

   • Extend the MaintenanceModeListener to fetch IPs from a database:

     // src/EventListener/CustomMaintenanceListener.php
     use Drawik\MaintenanceModeBundle\EventListener\MaintenanceModeListener;
     
     class CustomMaintenanceListener extends MaintenanceModeListener {
         public function isIpAllowed(string $ip): bool {
             // Fetch from DB or API
             return in_array($ip, $this->fetchAllowedIps());
         }
     }
     

   • Register the service in config/services.yaml:

     services:
         App\EventListener\CustomMaintenanceListener:
             tags: ['kernel.event_listener', { event: 'kernel.request', method: 'onKernelRequest' }]
     

3. Multi-Tenant Maintenance:

   • Use the lock_file_path config to create tenant-specific lock files:

     lock_file_path: '%kernel.project_dir%/var/maintenance_%tenant_id%.lock'
     

   • Enable/disable per tenant with:

     echo "1" > var/maintenance_tenant1.lock
     

4. API vs. Web Maintenance:

   • Differentiate between API and web traffic by checking the REQUEST_URI in the listener:

     if (str_starts_with($request->getUri(), '/api')) {
         return; // Skip maintenance for API
     }