Advanced Maintenance Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require shamarkellman/advanced-maintenance
   

   Add the service provider to config/app.php:

   Shamarkellman\AdvancedMaintenance\AdvancedMaintenanceServiceProvider::class,
   

2. Publish Config & Views:

   php artisan vendor:publish --provider="Shamarkellman\AdvancedMaintenance\AdvancedMaintenanceServiceProvider" --force
   

   • Config: config/advanced-maintenance.php
   • Views: resources/views/vendor/advanced-maintenance/

3. Enable Maintenance Mode:

   php artisan down --secret=your-secret-key
   

4. First Use Case:

   • Edit config/advanced-maintenance.php to define excluded_routes (e.g., ['admin', 'admin/*']).
   • Customize the 503 error page at resources/views/vendor/advanced-maintenance/503.blade.php.

Implementation Patterns

Core Workflows

1. Admin/CMS Access During Maintenance:

   • Configure excluded_routes in advanced-maintenance.php to whitelist admin routes (e.g., ['admin/*']).
   • Test by running php artisan down and verifying admin routes remain accessible.

2. Coming Soon Page:

   • Replace resources/views/vendor/advanced-maintenance/503.blade.php with a custom "Coming Soon" template.
   • Use Blade directives (e.g., @if(config('advanced-maintenance.show_countdown'))) to add dynamic elements like countdowns.

3. Dynamic Route Whitelisting:

   • Use middleware to conditionally exclude routes:

     // app/Http/Kernel.php
     'web' => [
         \Shamarkellman\AdvancedMaintenance\Middleware\Maintenance::class,
         // Other middleware...
     ],
     

   • Override the authorize() method in the Maintenance middleware (if extended) to add logic (e.g., IP-based access).

4. Environment-Specific Config:

   • Use Laravel’s environment variables to toggle maintenance mode:

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

   • Trigger via CLI:

     php artisan down --secret=$(MAINTENANCE_SECRET)
     

5. Integration with Deployment:

   • Hook into deploy:post in Laravel Forge/Envoyer or CI/CD pipelines to enable maintenance mode before updates:

     php artisan down --secret=$MAINTENANCE_SECRET --message="Site under maintenance"
     

Gotchas and Tips

Pitfalls

1. Route Caching Conflicts:

   • If using php artisan route:cache, ensure excluded_routes are updated before caching:

     php artisan route:clear  # Clear cache if routes change
     

   • Test route exclusions thoroughly after caching.

2. Middleware Order Matters:

   • Place Maintenance middleware before auth middleware in Kernel.php to avoid redirect loops for excluded routes.

3. Secret Key Security:

   • The --secret flag is required for down commands. Store it in .env:

     MAINTENANCE_SECRET=your-strong-secret-here
     

   • Never hardcode secrets in config files.

4. View Override Pitfalls:

   • Ensure the custom 503.blade.php extends the base layout or includes necessary CSS/JS. Example:

     @extends('layouts.app')
     @section('content')
         <h1>Coming Soon!</h1>
         <!-- Custom content -->
     @endsection
     

5. Laravel 8+ Compatibility:

   • The package targets Laravel 5.4. For newer versions, manually handle route exclusions via middleware or use app()->runningInConsole() checks in custom logic.

Debugging Tips

1. Check Excluded Routes:

   • Temporarily add a dd() in the middleware to verify routes are being excluded:

     // app/Http/Middleware/Maintenance.php (if extended)
     public function handle($request, Closure $next)
     {
         dd($this->isExcluded($request)); // Debug exclusion logic
         return $next($request);
     }
     

2. Log Maintenance Events:

   • Extend the middleware to log maintenance mode activations:

     \Log::info('Maintenance mode enabled for IP: ' . $request->ip());
     

3. Test Locally:

   • Use php artisan down --secret=test and test excluded routes in a local environment before deploying.

Extension Points

1. Custom Middleware Logic:

   • Extend the Maintenance middleware to add dynamic exclusions (e.g., user roles):

     // app/Http/Middleware/CustomMaintenance.php
     public function handle($request, Closure $next)
     {
         if (auth()->check() && auth()->user()->isAdmin()) {
             return $next($request);
         }
         return parent->handle($request, $next);
     }
     

2. API Endpoints:

   • Exclude API routes by prefix:

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

   • For granular control, use middleware groups in Kernel.php:

     'api' => [
         \Shamarkellman\AdvancedMaintenance\Middleware\Maintenance::class,
         'throttle:60',
     ],
     

3. Countdown Functionality:

   • Add a countdown to 503.blade.php using JavaScript:

     <script>
         const launchDate = new Date("{{ config('advanced-maintenance.launch_date') }}").getTime();
         const countdown = setInterval(() => {
             const now = new Date().getTime();
             const distance = launchDate - now;
             // Update DOM with days/hours/minutes
         }, 1000);
     </script>
     

   • Store launch_date in advanced-maintenance.php:

     'launch_date' => '2023-12-31',
     

4. Multi-Language Support:

   • Use Laravel’s localization in 503.blade.php:

     @lang('messages.coming_soon')
     

   • Add translations to resources/lang/en/messages.php:

     return [
         'coming_soon' => 'We will be back soon!',
     ];