Laravel Maintenance Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dginxreal/laravel-maintenance
   

   Publish the config file:

   php artisan vendor:publish --provider="DGINXREAL\Maintenance\MaintenanceServiceProvider" --tag="config"
   

2. Enable Maintenance Mode

   php artisan maintenance:enable
   

   • This immediately routes all requests to a customizable maintenance page.

3. First Use Case: Scheduled Downtime

   • Configure downtime in config/maintenance.php:

     'downtime' => [
         'enabled' => true,
         'start' => '2024-01-01 00:00:00',
         'end' => '2024-01-01 01:00:00',
     ],
     

   • Run:

     php artisan maintenance:downtime
     

Implementation Patterns

1. Conditional Maintenance Mode

• Dynamic Enablement via Middleware Use the MaintenanceModeMiddleware to conditionally enable/disable maintenance based on logic (e.g., user roles, API keys):

  protected function boot()
  {
      $this->middleware('maintenance', function ($request) {
          return !$request->user()->isAdmin() && config('app.env') === 'production';
      });
  }
  

• IP Whitelisting Allow specific IPs (e.g., your own) to bypass maintenance:

  'allowed_ips' => [
      '127.0.0.1',
      '192.168.1.100',
  ],
  

2. Custom Maintenance Pages

• Override Default Views Publish views:

  php artisan vendor:publish --provider="DGINXREAL\Maintenance\MaintenanceServiceProvider" --tag="views"
  

  Customize resources/views/vendor/maintenance/{page}.blade.php (e.g., maintenance.blade.php).

• Dynamic Content Pass data to the maintenance view via middleware:

  $response = app(\DGINXREAL\Maintenance\Facades\Maintenance::class)->response();
  return $response->withData(['message' => 'System upgrade in progress!']);
  

3. API-Specific Maintenance

• Exclude API Routes Use route middleware groups:

  Route::middleware(['api', 'maintenance:exclude'])->group(function () {
      Route::prefix('api')->uses(...);
  });
  

  Configure exclusions in config/maintenance.php:

  'excluded_routes' => ['api/*'],
  

• API Status Endpoint Add a health check endpoint:

  Route::get('/status', function () {
      return response()->json([
          'status' => app(\DGINXREAL\Maintenance\Facades\Maintenance::class)->isEnabled() ? 'down' : 'up',
      ]);
  });
  

4. Scheduled Downtime Workflows

• Cron Job Integration Use Laravel’s scheduler to toggle maintenance:

  $schedule->command('maintenance:enable')->dailyAt('3:00');
  $schedule->command('maintenance:disable')->dailyAt('4:00');
  

• Graceful Degradation Combine with queue:work to process pending jobs before downtime:

  php artisan maintenance:enable --queue-flush
  

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear routes/cache after enabling maintenance:

     php artisan route:clear
     php artisan config:clear
     

   • Ensure config('cache.enabled') is false during testing if maintenance isn’t triggering.

2. Middleware Order Matters

   • Place MaintenanceModeMiddleware before TrustProxies or VerifyCsrfToken to avoid bypassing maintenance.

3. Downtime Timezone

   • Downtime times use the system timezone. Override in config/maintenance.php:

     'timezone' => 'America/New_York',
     

4. Queue Jobs During Downtime

   • Jobs dispatched during maintenance will fail silently. Use --queue-flush to process them first:

     php artisan maintenance:enable --queue-flush
     

Debugging Tips

• Check Maintenance Status

  dd(app(\DGINXREAL\Maintenance\Facades\Maintenance::class)->isEnabled());
  

• Log Middleware Execution Add debug logs in app/Http/Middleware/MaintenanceModeMiddleware.php:

  Log::debug('Maintenance check triggered for IP: ' . $request->ip());
  

Extension Points

1. Custom Maintenance Logic Extend the MaintenanceService:

   namespace App\Services;
   use DGINXREAL\Maintenance\MaintenanceService;
   
   class CustomMaintenanceService extends MaintenanceService
   {
       public function isEnabled()
       {
           if (parent::isEnabled()) {
               return true;
           }
           // Add custom logic (e.g., check database flag)
           return DB::table('maintenance_flags')->exists();
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(
       \DGINXREAL\Maintenance\Contracts\Maintenance::class,
       App\Services\CustomMaintenanceService::class
   );
   

2. Event-Based Maintenance Listen for maintenance events to trigger side effects (e.g., notifications):

   \DGINXREAL\Maintenance\Events\MaintenanceEnabled::class => [
       \App\Listeners\SendDowntimeNotification::class,
   ],
   

3. Multi-Tenant Maintenance Scope maintenance per tenant using a custom guard:

   'tenant_guard' => 'tenant',
   

   Implement TenantGuard in config/maintenance.php.