Maintenance Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mjtheone/simple-maintenance
   

   Publish the config file:

   php artisan vendor:publish --provider="MJTheOne\SimpleMaintenance\SimpleMaintenanceServiceProvider" --tag="config"
   

2. Enable Maintenance Mode

   php artisan maintenance:enable
   

   This creates a maintenance file in storage/framework/maintenance.php.

3. Disable Maintenance Mode

   php artisan maintenance:disable
   

4. Check Current Status

   php artisan maintenance:status
   

First Use Case

• Quickly block all traffic during deployments or database migrations.
• Customize the maintenance page by modifying resources/views/vendor/simple-maintenance/maintenance.blade.php (if the package supports view overrides).

Implementation Patterns

Workflow Integration

1. Automate with Deploy Scripts Add maintenance mode at the start of your deployment script:

   php artisan maintenance:enable
   # Run migrations, deploy code, etc.
   php artisan maintenance:disable
   

2. Conditional Logic in Routes/Middleware Check maintenance status in middleware or route closures:

   if (app('maintenance')->isEnabled()) {
       abort(503, 'Site under maintenance');
   }
   

3. Custom Maintenance Pages Override the default view by publishing assets:

   php artisan vendor:publish --tag="simple-maintenance-views"
   

   Then edit resources/views/vendor/simple-maintenance/maintenance.blade.php.

4. Environment-Specific Maintenance Use config to enable/disable per environment:

   // config/simple-maintenance.php
   'enabled' => env('MAINTENANCE_MODE', false),
   

Integration Tips

• Laravel Forge/Envoyer: Hook into deployment scripts to toggle maintenance mode.
• Laravel Horizon: Disable queues during maintenance to prevent background jobs from interfering.
• Laravel Echo/Pusher: Pause event broadcasting if using real-time features.

Gotchas and Tips

Pitfalls

1. File Permissions Ensure storage/framework/maintenance.php is writable:

   chmod -R 775 storage/framework
   

   • Symptom: maintenance:enable fails silently.

2. Caching Issues Clear config cache after enabling/disabling:

   php artisan config:clear
   

   • Symptom: Maintenance mode appears stuck.

3. No Built-in Whitelisting The package lacks IP whitelisting. Workaround:

   if (app('maintenance')->isEnabled() && !in_array(request()->ip(), ['127.0.0.1', '192.168.1.100'])) {
       abort(503);
   }
   

4. No API for Programmatic Control Directly manipulate the file if needed:

   file_put_contents(storage_path('framework/maintenance.php'), '<?php return true;');
   

Debugging

• Verify File Existence Check if storage/framework/maintenance.php exists when mode seems stuck.
• Check Config Overrides Ensure no other packages (e.g., laravel-debugbar) interfere with middleware order.

Extension Points

1. Custom Drivers Extend MJTheOne\SimpleMaintenance\Drivers\Driver to use a database or cache driver.
2. Event Listeners Listen for maintenance.enabled/maintenance.disabled events (if the package supports them).
3. Middleware Integration Add to app/Http/Kernel.php:

   protected $middlewareGroups = [
       'web' => [
           // ...
           \MJTheOne\SimpleMaintenance\Http\Middleware\MaintenanceMiddleware::class,
       ],
   ];