Maintenance Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dopse7/maintenance-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Dopse7\MaintenanceBundle\Dopse7MaintenanceBundle::class => ['all' => true],
   ];
   

2. Publish Configuration

   php bin/console dopse7:maintenance:install
   

   This generates config/packages/dopse7_maintenance.yaml with default settings.

3. First Use Case Enable maintenance mode immediately:

   php bin/console dopse7:maintenance:enable
   

   Disable it:

   php bin/console dopse7:maintenance:disable
   

Key Configuration Options

• Storage Backend: Choose between file, memcache, or database (default: file).
• Authorized IPs: Whitelist IPs in config/packages/dopse7_maintenance.yaml:

  dopse7_maintenance:
      authorized_ips: ['127.0.0.1', '192.168.1.100/24']
  

Implementation Patterns

Workflows

1. Scheduled Deployments Use a pre-deploy hook to enable maintenance mode, then disable it post-deploy:

   # In deploy script
   php bin/console dopse7:maintenance:enable
   # ... run migrations, deploy code ...
   php bin/console dopse7:maintenance:disable
   

2. Database-Backed Mode Configure database storage in config/packages/dopse7_maintenance.yaml:

   dopse7_maintenance:
       storage: database
       database_table: maintenance_mode
   

   Run migrations:

   php bin/console make:migration
   php bin/console doctrine:migrations:migrate
   

3. Dynamic IP Whitelisting Extend the bundle by overriding the MaintenanceListener to fetch authorized IPs from an API or database:

   // src/EventListener/CustomMaintenanceListener.php
   public function onKernelRequest(GetResponseEvent $event) {
       $ips = $this->fetchAuthorizedIpsFromApi(); // Custom logic
       $this->maintenanceChecker->setAuthorizedIps($ips);
       // ... rest of logic
   }
   

Integration Tips

• Symfony Flex: Works seamlessly with Symfony Flex projects.
• Environment-Specific Config: Use %env(respect_valid_root=true)% in config/packages/dopse7_maintenance.yaml for environment variables:

  dopse7_maintenance:
      authorized_ips: ['%env(MAINTENANCE_IPS)%']
  

• Custom Maintenance Page: Override the default Twig template by copying vendor/lexik/maintenance-bundle/Resources/views/maintenance.html.twig to templates/maintenance.html.twig.

Gotchas and Tips

Pitfalls

1. Caching Issues If using memcache, ensure the cache server is running and accessible. Clear cache after enabling/disabling:

   php bin/console cache:clear
   

2. Database Storage Quirks

   • The migration for database storage creates a maintenance_mode table. If manually creating the table, ensure it matches the expected schema:

     CREATE TABLE maintenance_mode (
         id INT AUTO_INCREMENT PRIMARY KEY,
         enabled TINYINT(1) NOT NULL DEFAULT 0,
         created_at DATETIME NOT NULL
     );
     

   • Race conditions may occur if multiple processes enable/disable maintenance simultaneously. Use transactions or a mutex.

3. IP Whitelisting Edge Cases

   • Subnet notation (e.g., 192.168.1.0/24) requires the symfony/security-csrf component for parsing. Install it if missing:

     composer require symfony/security-csrf
     

   • IPv6 addresses are not natively supported. Use a custom validator or pre-process IPs.

Debugging

• Check Mode Verify maintenance mode status without triggering the 503:

  php bin/console dopse7:maintenance:check
  

• Log Output Enable debug mode in config/packages/dopse7_maintenance.yaml:

  dopse7_maintenance:
      debug: true
  

  Logs will appear in var/log/dev.log.

Extension Points

1. Custom Storage Implement Dopse7\MaintenanceBundle\Storage\StorageInterface for custom backends (e.g., Redis):

   class RedisStorage implements StorageInterface {
       public function isEnabled() { /* ... */ }
       public function enable() { /* ... */ }
       public function disable() { /* ... */ }
   }
   

   Register it in config/services.yaml:

   Dopse7\MaintenanceBundle\Storage\StorageInterface: '@redis_storage'
   

2. Event Listeners Subscribe to maintenance.enable and maintenance.disable events to trigger side effects (e.g., log deployments):

   // src/EventListener/MaintenanceLogger.php
   public static function getSubscribedEvents() {
       return [
           KernelEvents::MAINTENANCE_ENABLE => 'onMaintenanceEnable',
           KernelEvents::MAINTENANCE_DISABLE => 'onMaintenanceDisable',
       ];
   }
   

3. Override Templates Copy the Twig template to templates/bundles/dopse7maintenance/maintenance.html.twig to customize the 503 page. Extend the base template:

   {% extends 'bundles/dopse7maintenance/maintenance.html.twig' %}
   {% block body %}
       {{ parent() }}
       <p>Custom maintenance message here.</p>
   {% endblock %}
   

Configuration Quirks

• File Storage Path Default path: var/maintenance. Ensure the directory is writable by the web server user.
• Environment Variables Use MAINTENANCE_ENABLED to control mode via environment (e.g., in Docker):

  dopse7_maintenance:
      enabled: '%env(bool:MAINTENANCE_ENABLED)%'