Maintenance Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ady/maintenance-bundle
   

   Add to config/bundles.php:

   Ady\MaintenanceBundle\AdyMaintenanceBundle::class => ['all' => true],
   

2. First Use Case Enable maintenance mode:

   php bin/console ady:maintenance:enable
   

   Disable it:

   php bin/console ady:maintenance:disable
   

3. Where to Look First

   • Configuration: config/packages/ady_maintenance.yaml (default path)
   • Commands: src/Command/ in the bundle for customization
   • Templates: templates/AdyMaintenanceBundle/ for overriding default views

Implementation Patterns

Core Workflows

1. Conditional Maintenance Use the isInMaintenance() helper in controllers:

   if (\Ady\MaintenanceBundle\Helper\MaintenanceHelper::isInMaintenance()) {
       return redirect()->route('maintenance.page');
   }
   

2. Custom Maintenance Pages Override the default Twig template:

   • Copy templates/AdyMaintenanceBundle/maintenance.html.twig to your project’s templates/ directory.
   • Extend with custom logic (e.g., show a contact form).

3. API Maintenance Mode Combine with middleware (e.g., MaintenanceMiddleware) to block API routes:

   // app/Http/Kernel.php
   protected $middlewareGroups = [
       'api' => [
           // ...
           \Ady\MaintenanceBundle\Http\Middleware\MaintenanceMiddleware::class,
       ],
   ];
   

4. Scheduled Maintenance Use Laravel’s scheduler to enable/disable mode:

   * * * * * cd /path-to-project && php artisan ady:maintenance:enable
   

   (Disable via cron or manually.)

Integration Tips

• Laravel Mix: Exclude maintenance assets from builds by checking isInMaintenance() in webpack.mix.js.
• Queue Workers: Disable queue workers during maintenance to prevent background jobs from interfering:

  if (MaintenanceHelper::isInMaintenance()) {
      Queue::pause();
  }
  

• Environment-Specific: Use .env to toggle maintenance per environment:

  MAINTENANCE_MODE=true
  

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear cache after enabling/disabling maintenance:

     php bin/console cache:clear
     

   • If using Varnish/Nginx cache, purge explicitly or configure cache headers to respect X-Maintenance-Mode.

2. Route Leaks

   • Ensure MaintenanceMiddleware is not added to web middleware (unless intentional).
   • Test critical routes (e.g., /health) to confirm they bypass maintenance.

3. Database Locks

   • Avoid running migrations or long-running tasks while in maintenance mode to prevent timeouts.

Debugging

• Check Status Programmatically

  dd(\Ady\MaintenanceBundle\Helper\MaintenanceHelper::isInMaintenance());
  

• Log Commands Wrap commands in a try-catch to log failures:

  try {
      $this->call('ady:maintenance:enable');
  } catch (\Exception $e) {
      Log::error('Maintenance enable failed: ' . $e->getMessage());
  }
  

Extension Points

1. Custom Logic Extend the MaintenanceChecker service to add conditions:

   // config/packages/ady_maintenance.yaml
   services:
       Ady\MaintenanceBundle\Checker\MaintenanceChecker:
           arguments:
               $customCheckers: ['App\Checker\CustomMaintenanceChecker']
   

2. Override Templates

   • Copy maintenance.html.twig to templates/AdyMaintenanceBundle/ and modify.
   • For JSON API responses, override maintenance.json.twig.

3. Multi-Tenant Support Store maintenance status per tenant in a pivot table and modify the checker:

   public function isInMaintenance(): bool {
       return Tenant::find($this->tenantId)?->isInMaintenance ?? false;
   }
   

Config Quirks

• Default Paths: The bundle assumes templates/ and config/ are in the root. Adjust paths in config/packages/ady_maintenance.yaml if needed.
• Environment Variables: The bundle respects APP_ENV but not MAINTENANCE_MODE by default. Override the checker to use it:

  # config/packages/ady_maintenance.yaml
  parameters:
      ady_maintenance.enabled: '%env(bool:MAINTENANCE_MODE,false)%'