Maintenance Switch Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require brickx/maintenance-switch
   php artisan vendor:publish --tag="maintenance-switch-config"
   

   • Verify the config file appears in config/maintenance-switch.php.

2. Register the Plugin Add the plugin to your Filament admin panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Brickx\MaintenanceSwitch\MaintenanceSwitchPlugin::make(),
           ]);
   }
   

3. First Use Case

   • Access your Filament panel and locate the new toggle button (default: top-right corner).
   • Toggle maintenance mode on to test. Refresh the frontend to confirm the maintenance page appears.
   • Toggle off to revert.

Implementation Patterns

Core Workflows

1. Basic Toggle Integration

   • Use the default toggle placement (render_hook: 'global-search.before').
   • Customize visibility via config:

     'permissions' => true, // Restrict to users with 'super-admin' role
     'role' => 'super-admin',
     

2. Secret Token Bypass

   • Set a secret token in .env:

     MAINTENANCE_SWITCH_SECRET=your_secure_token_here
     

   • Update config:

     'secret' => env('MAINTENANCE_SWITCH_SECRET'),
     

   • Bypass maintenance mode by appending ?secret=your_token to any URL.

3. Dynamic Refresh

   • Enable auto-refresh of the toggle state:

     'refresh' => true,
     

   • Useful for multi-tab environments where toggles may desync.

4. Theming & Placement

   • Customize the icon or toggle size:

     'icon' => 'heroicon-o-cog', // Use any Heroicon
     'tiny_toggle' => true,
     

   • Reposition the toggle via render_hook:

     'render_hook' => 'navigation.items.after',
     

5. Conditional Visibility

   • Hide the toggle for specific environments:

     if (app()->environment('production')) {
         config(['maintenance-switch.permissions' => true]);
     }
     

Integration Tips

• Filament Widgets: Combine with other Filament widgets (e.g., StatsOverviewWidget) for a unified dashboard.
• Event Listeners: Listen for maintenance mode changes:

  use Brickx\MaintenanceSwitch\Events\MaintenanceModeChanged;
  
  MaintenanceModeChanged::listen(function ($enabled) {
      Log::info("Maintenance mode set to: {$enabled}");
  });
  

• Custom Maintenance Page: Extend the default maintenance page by publishing views:

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

Gotchas and Tips

Pitfalls

1. Config Overrides

   • Ensure config values in config/maintenance-switch.php take precedence over defaults.
   • Debugging Tip: Use php artisan config:clear if changes aren’t reflected.

2. Secret Token Security

   • Never hardcode secrets in config/maintenance-switch.php. Always use .env.
   • Gotcha: If the token is leaked, reset it immediately and clear cached routes:

     php artisan route:clear
     

3. Permission Conflicts

   • If using permissions: true or role:, verify the Filament user has the correct permissions.
   • Debugging Tip: Check Filament’s user debug panel (/filament/admin/debug) for role assignments.

4. Caching Issues

   • Maintenance mode may persist due to Laravel’s route caching. Clear it after toggling:

     php artisan route:clear
     

   • For production, use:

     php artisan route:cache
     

5. Plugin Registration Order

   • Register MaintenanceSwitchPlugin after other plugins that might depend on the navigation structure (e.g., NavigationItems).

Debugging

• Toggle Not Showing?

  • Verify the render_hook exists in your Filament panel. Check available hooks in filament-support/src/Resources/Views/Layouts/Navigation/Items.php.
  • Fix: Use 'render_hook' => 'global-search.before' as a fallback.

• Maintenance Page Not Triggering?

  • Ensure APP_ENV is not local (maintenance mode is often disabled locally by default).
  • Debug: Temporarily set 'secret' => 'test' in config and test with ?secret=test.

• CSRF Token Errors

  • If the toggle fails silently, ensure your Filament panel’s middleware includes web (for CSRF protection).

Extension Points

1. Custom Toggle Logic Override the toggle behavior by extending the plugin:

   use Brickx\MaintenanceSwitch\MaintenanceSwitchPlugin;
   
   class CustomMaintenanceSwitch extends MaintenanceSwitchPlugin
   {
       protected function toggleMaintenanceMode(bool $enabled): void
       {
           // Custom logic (e.g., log, notify Slack)
           parent::toggleMaintenanceMode($enabled);
       }
   }
   

2. Dynamic Secret Tokens Fetch secrets from an API or database:

   'secret' => fn() => DB::table('secrets')->where('key', 'maintenance')->value('value'),
   

3. Multi-Tenant Support Scope maintenance mode to tenants by modifying the toggleMaintenanceMode method to check the current tenant:

   if (tenant()->is('acme')) {
       parent::toggleMaintenanceMode($enabled);
   }
   

4. Localization Publish translations and extend them:

   php artisan vendor:publish --tag="maintenance-switch-translations"
   

   • Override in resources/lang/en/maintenance-switch.php:

     return [
         'toggle_label' => 'Maintenance Mode (Custom Label)',
     ];