Maintenance Bundle Deprecated Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require lexik/maintenance-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Lexik\Bundle\MaintenanceBundle\LexikMaintenanceBundle::class => ['all' => true],
   ];
   

2. Configuration: Publish the default config:

   php artisan vendor:publish --tag=lexik_maintenance_config
   

   Update config/lexik_maintenance.yaml with your preferred storage (file, memcache, or database) and allowed IPs:

   lexik_maintenance:
       storage:
           type: file
           file: '%kernel.project_dir%/var/maintenance'
       authorized_ips: ['127.0.0.1', '192.168.1.100']
   

3. First Use Case: Enable maintenance mode:

   php artisan lexik:maintenance:enable
   

   Disable it:

   php artisan lexik:maintenance:disable
   

Implementation Patterns

Workflows

1. Pre-Deployment Maintenance:

   • Enable maintenance mode before deploying updates:

     php artisan lexik:maintenance:enable --env=production
     

   • Disable after deployment completes.

2. IP-Based Whitelisting:

   • Configure authorized_ips in lexik_maintenance.yaml to allow specific IPs (e.g., staging servers, CI/CD pipelines).
   • Useful for zero-downtime deployments:

     authorized_ips: ['10.0.0.1/24', '192.168.1.5']
     

3. Custom Storage Backend:

   • For distributed environments, use database storage (requires doctrine/orm):

     storage:
         type: database
     

   • For high-performance needs, integrate memcache (requires ext-memcache):

     storage:
         type: memcache
         servers: ['127.0.0.1:11211']
     

4. Integration with Laravel Artisan:

   • Chain commands in post-deploy hooks (e.g., Deployer):

     task('deploy:post')->do(function () {
         run('php artisan lexik:maintenance:disable');
     });
     

5. Dynamic Maintenance Pages:

   • Override the default 503 page by extending the bundle’s template:

     # templates/LexikMaintenanceBundle/Maintenance/maintenance.html.twig
     {% extends 'base.html.twig' %}
     {% block body %}
         <h1>Under Maintenance</h1>
         <p>We’ll be back soon!</p>
     {% endblock %}
     

Gotchas and Tips

Pitfalls

1. File Storage Permissions:

   • Ensure the maintenance file (var/maintenance) is writable by the web server:

     chmod 644 var/maintenance
     

   • Debugging: Check storage/logs/laravel.log for permission errors.

2. Caching Headaches:

   • If using memcache, ensure the server is running and accessible. Test with:

     php artisan lexik:maintenance:status
     

   • Clear cache after disabling maintenance:

     php artisan cache:clear
     

3. Database Storage Quirks:

   • Requires a maintenance table. Run migrations if missing:

     php artisan doctrine:migrations:diff
     php artisan doctrine:migrations:migrate
     

   • Ensure the maintenance table has the correct schema (check bundle docs).

4. IP Whitelisting Edge Cases:

   • CIDR notation (e.g., 192.168.1.0/24) may not work out-of-the-box. Validate IPs manually:

     use Lexik\MaintenanceBundle\Security\IpChecker;
     $ipChecker = new IpChecker(['192.168.1.0/24']);
     $ipChecker->isIpAuthorized('192.168.1.5'); // true
     

5. Environment-Specific Config:

   • Override config per environment (e.g., config/lexik_maintenance_production.yaml):

     authorized_ips: ['%env(DEPLOY_IP)%']
     

   • Load in config/packages/lexik_maintenance.yaml:

     imports:
         - { resource: lexik_maintenance_%.yaml }
     

Debugging Tips

1. Check Maintenance Status:

   php artisan lexik:maintenance:status
   

   Output:

   Maintenance mode is enabled (storage: file)
   

2. Simulate 503 Locally:

   • Use curl to test the 503 response:

     curl -I http://localhost
     

   • Expected: HTTP/1.1 503 Service Unavailable.

3. Log Maintenance Events:

   • Extend the bundle to log enable/disable actions:

     // src/EventListener/MaintenanceLogger.php
     use Lexik\MaintenanceBundle\Event\MaintenanceEvent;
     
     class MaintenanceLogger implements EventSubscriber {
         public static function getSubscribedEvents() {
             return [
                 MaintenanceEvent::ENABLE => 'onEnable',
                 MaintenanceEvent::DISABLE => 'onDisable',
             ];
         }
     
         public function onEnable(MaintenanceEvent $event) {
             \Log::info('Maintenance enabled', ['storage' => $event->getStorage()->getType()]);
         }
     }
     

Extension Points

1. Custom Storage Adapter:

   • Implement Lexik\MaintenanceBundle\Storage\StorageInterface for custom backends (e.g., Redis):

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

   • Register in services.yaml:

     lexik_maintenance.storage:
         class: App\Storage\RedisStorage
     

2. Dynamic IP Whitelisting:

   • Fetch authorized IPs from an API or database:

     $authorizedIps = $this->fetchIpsFromApi();
     $ipChecker = new IpChecker($authorizedIps);
     

3. Multi-Tenant Support:

   • Store maintenance flags per tenant in the database:

     // Custom storage logic
     $isEnabled = DB::table('tenants')
         ->where('id', $tenantId)
         ->value('maintenance_enabled');