Maintenance Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require atournayre/maintenance-bundle
   

2. Enable the bundle in config/bundles.php:

   return [
       Atournayre\MaintenanceBundle\AtournayreMaintenanceBundle::class => ['all' => true],
   ];
   

3. Configure .env with basic settings:

   MAINTENANCE_IS_ENABLED=false
   MAINTENANCE_AUTHORIZED_IPS=localhost,127.0.0.1
   

4. Update services.yaml to bind env vars:

   parameters:
       atournayre_maintenance.is_enabled: '%env(MAINTENANCE_IS_ENABLED)%'
       atournayre_maintenance.authorized_ips: '%env(MAINTENANCE_AUTHORIZED_IPS)%'
   

5. First use case: Enable maintenance immediately:

   php bin/console maintenance --enable
   

Implementation Patterns

Core Workflows

1. Scheduled Deployments

   • Use --start to schedule maintenance for a future datetime (e.g., pre-deployment):

     php bin/console maintenance --start="2024-01-01 00:00:00" --enable
     

   • Combine with --add-ip to whitelist your CI/CD server’s IP.

2. Zero-Downtime Maintenance

   • Enable maintenance before deploying, then disable it after:

     # Pre-deploy
     php bin/console maintenance --enable --add-ip="your-server-ip"
     
     # Post-deploy
     php bin/console maintenance --disable
     

3. Environment-Specific Configs

   • Override .env per environment (e.g., .env.prod):

     MAINTENANCE_IS_ENABLED=false  # Default: off in production
     MAINTENANCE_AUTHORIZED_IPS=123.45.67.89  # Whitelist only your team's IPs
     

   • Use --debug to verify configs:

     php bin/console maintenance --debug
     

4. Custom Templates

   • Override the default Twig template for maintenance pages:

     mkdir -p templates/bundles/AtournayreMaintenanceBundle
     cp -r vendor/atournayre/maintenance-bundle/Resources/views/* templates/bundles/AtournayreMaintenanceBundle/
     

   • Extend the base template (maintenance.html.twig) to add:
     • Custom styling (e.g., match your app’s theme).
     • Dynamic content (e.g., show estimated downtime).

5. CI/CD Integration

   • Add maintenance commands to your deployment script:

     # In your deploy.sh
     php bin/console maintenance --enable --add-ip="$DEPLOY_IP"
     # Run migrations/deploy...
     php bin/console maintenance --disable
     

Gotchas and Tips

Pitfalls

1. IP Whitelisting Quirks

   • IPv6 Support: The bundle supports IPv6, but ensure your .env uses the correct format (e.g., ::1 for localhost).
   • Comma-Separated Values: IPs in MAINTENANCE_AUTHORIZED_IPS must be comma-separated (no spaces). Example:

     MAINTENANCE_AUTHORIZED_IPS=192.168.1.1,2001:0db8::1
     

   • Debugging: Use --dump-ips to verify whitelisted IPs:

     php bin/console maintenance --dump-ips
     

2. Timezone Sensitivity

   • The --start datetime uses the server’s timezone. If your server is in UTC but you’re in EST, add the timezone explicitly:

     php bin/console maintenance --start="2024-01-01 00:00:00 America/New_York"
     

3. Template Overrides

   • Symfony 5+ Note: The templates/bundles/ structure works in Symfony 4.4+. For Symfony 5+, use templates/AtournayreMaintenanceBundle/ instead.
   • Caching: Clear the cache after overriding templates:

     php bin/console cache:clear
     

4. Command Conflicts

   • Avoid mixing --enable/--disable with --start. Use --start alone to schedule maintenance without enabling it immediately.

5. Environment Variables

   • Missing .env: If MAINTENANCE_IS_ENABLED is undefined, the bundle defaults to false. Always define it explicitly.
   • Local Development: Use .env.local.php for local overrides (e.g., disable maintenance for your dev machine).

Debugging Tips

1. Verify Configs

   php bin/console debug:config atournayre_maintenance
   

   • Checks if parameters are correctly loaded from .env.

2. Check Middleware

   • The bundle adds a middleware to block requests. If maintenance is enabled but pages still load:
     • Ensure the bundle is enabled in bundles.php.
     • Verify no other middleware (e.g., Symfony\WebServerBundle) is overriding the response.

3. Log Entries

   • Add this to config/packages/dev/monolog.yaml to log maintenance events:

     handlers:
         maintenance:
             type: stream
             path: "%kernel.logs_dir%/maintenance.log"
             level: info
             channels: ["maintenance"]
     

   • Then, in your code, log events:

     $this->logger->info('Maintenance enabled', ['bundle' => 'AtournayreMaintenanceBundle']);
     

Extension Points

1. Custom Logic for Maintenance

   • Extend the bundle by creating a custom command that hooks into the maintenance service:

     // src/Command/CustomMaintenanceCommand.php
     use Atournayre\MaintenanceBundle\Service\MaintenanceService;
     
     class CustomMaintenanceCommand extends Command {
         protected static $defaultName = 'app:custom-maintenance';
         private $maintenanceService;
     
         public function __construct(MaintenanceService $maintenanceService) {
             $this->maintenanceService = $maintenanceService;
         }
     
         protected function execute(InputInterface $input, OutputInterface $output): int {
             $this->maintenanceService->enable();
             $this->maintenanceService->addIp('192.168.1.100');
             $output->writeln('Custom maintenance enabled!');
             return Command::SUCCESS;
         }
     }
     

2. Event Listeners

   • Listen for maintenance state changes by subscribing to the maintenance.enabled and maintenance.disabled events (if the bundle exposes them). If not, create a proxy service:

     // src/Service/MaintenanceProxy.php
     use Atournayre\MaintenanceBundle\Service\MaintenanceService;
     
     class MaintenanceProxy {
         private $maintenanceService;
     
         public function __construct(MaintenanceService $maintenanceService) {
             $this->maintenanceService = $maintenanceService;
             $this->maintenanceService->enable(); // Example trigger
         }
     }
     

3. Database-Backed Maintenance

   • Store maintenance state in a database by extending the MaintenanceService:

     // src/Service/DatabaseMaintenanceService.php
     use Atournayre\MaintenanceBundle\Service\MaintenanceService;
     
     class DatabaseMaintenanceService extends MaintenanceService {
         public function enable() {
             // Save to DB first
             $this->entityManager->persist($this->createMaintenanceEntity());
             $this->entityManager->flush();
             // Then call parent
             parent::enable();
         }
     }
     

   • Bind the service in config/services.yaml:

     services:
         Atournayre\MaintenanceBundle\Service\MaintenanceService:
             class: App\Service\DatabaseMaintenanceService