Maintenance Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require coa/maintenance-bundle
   

   Add to config/app.php under providers:

   CoteOuest\MaintenanceBundle\MaintenanceBundle::class,
   

   Publish the config file:

   php artisan vendor:publish --provider="CoteOuest\MaintenanceBundle\MaintenanceBundle" --tag=config
   

2. Enable Maintenance Mode Run the Artisan command:

   php artisan maintenance:enable
   

   This immediately activates maintenance mode, showing a default "Under Maintenance" page.

3. Customize the Page Override the default template by publishing the view:

   php artisan vendor:publish --provider="CoteOuest\MaintenanceBundle\MaintenanceBundle" --tag=views
   

   Edit resources/views/maintenance.blade.php to customize the message, styling, or add a countdown.

4. First Use Case: Scheduled Downtime Enable maintenance mode before a deployment or database migration:

   php artisan maintenance:enable --message="Site undergoing maintenance. Back soon!"
   

   Disable it afterward:

   php artisan maintenance:disable
   

Implementation Patterns

Workflow Integration

1. Automated Deployment Scripts Integrate with deployment tools (e.g., GitHub Actions, Jenkins) to enable maintenance mode before deployment and disable it post-deployment:

   # In deploy script
   php artisan maintenance:enable --message="Deploying updates..."
   # Run deployment commands...
   php artisan maintenance:disable
   

2. Environment-Based Configuration Use the config/maintenance.php file to define environment-specific settings:

   'environments' => [
       'local' => false, // Disable in local
       'staging' => true, // Enable in staging
       'production' => true,
   ],
   

   Enable/disable via:

   php artisan maintenance:enable --env=production
   

3. Custom Middleware for Partial Maintenance Extend the bundle to allow maintenance mode for specific routes or IPs:

   // app/Http/Kernel.php
   protected $routeMiddleware = [
       'maintenance.partial' => \CoteOuest\MaintenanceBundle\Http\Middleware\PartialMaintenance::class,
   ];
   

   Apply to routes:

   Route::middleware(['maintenance.partial'])->group(function () {
       // Routes to exclude from maintenance
   });
   

4. API-Specific Maintenance Use the maintenance:enable command with the --api flag to show a JSON response for API requests:

   php artisan maintenance:enable --api --message='{"status":"maintenance","message":"Service unavailable"}'
   

Common Patterns

• Conditional Maintenance: Combine with Laravel’s config('app.debug') to disable maintenance in debug mode.
• Database Locks: Pair with database transactions or locks to ensure consistency during maintenance.
• Logging: Log maintenance events to storage/logs/laravel.log for auditing:

  \Log::info('Maintenance mode enabled by ' . auth()->user()?->name);
  

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear route cache after enabling/disabling maintenance:

     php artisan route:clear
     

   • Ensure config('cache.enabled') is false during maintenance if using cached routes.

2. Middleware Conflicts

   • The bundle’s middleware (MaintenanceMiddleware) runs early in the stack. If other middleware (e.g., auth) fails, it may not trigger the maintenance page. Test thoroughly.

3. Environment Mismatches

   • The environments config in maintenance.php is case-sensitive. Ensure it matches your .env values exactly.

4. Custom Views Not Loading

   • If overriding maintenance.blade.php, ensure the file exists in resources/views/ and the view is published correctly. Check for typos in the filename.

Debugging Tips

• Check Status Verify maintenance mode is active:

  php artisan maintenance:status
  

  Output: Maintenance mode is enabled.

• Log Middleware Execution Add debug logs to the middleware (vendor/coa/maintenance-bundle/src/Http/Middleware/MaintenanceMiddleware.php) to trace execution:

  \Log::debug('MaintenanceMiddleware executed for ' . $request->path());
  

• Test API Responses Use curl or Postman to test API responses:

  curl -i http://your-site.test/api/endpoint
  

  Expect a 503 Service Unavailable response if enabled.

Extension Points

1. Custom Error Pages Extend the MaintenanceController to return dynamic content:

   namespace App\Http\Controllers;
   use CoteOuest\MaintenanceBundle\Http\Controllers\MaintenanceController as BaseController;
   
   class MaintenanceController extends BaseController
   {
       public function show()
       {
           return response()->view('custom.maintenance', [], 503);
       }
   }
   

   Override the controller binding in AppServiceProvider:

   public function register()
   {
       $this->app->bind(
           \CoteOuest\MaintenanceBundle\Http\Controllers\MaintenanceController::class,
           App\Http\Controllers\MaintenanceController::class
       );
   }
   

2. IP Whitelisting Modify the middleware to allow specific IPs:

   // In MaintenanceMiddleware
   public function handle($request, Closure $next)
   {
       $ips = ['127.0.0.1', '192.168.1.100']; // Whitelisted IPs
       if (!in_array($request->ip(), $ips) && $this->isEnabled()) {
           return $this->showMaintenancePage($request);
       }
       return $next($request);
   }
   

3. Event Listeners Listen for maintenance mode changes to trigger side effects (e.g., notifications):

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \CoteOuest\MaintenanceBundle\Events\MaintenanceEnabled::class => [
           \App\Listeners\SendMaintenanceNotification::class,
       ],
   ];
   

4. Configuration Overrides Dynamically override settings via environment variables:

   // config/maintenance.php
   'message' => env('MAINTENANCE_MESSAGE', 'Under maintenance.'),
   

   Set in .env:

   MAINTENANCE_MESSAGE="We're back! Check our blog for updates."