Maintenance Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require arkanii/maintenance-bundle
   

   For non-Flex projects, manually add the bundle to config/bundles.php:

   Arkanii\MaintenanceBundle\ArkaniiMaintenanceBundle::class => ['all' => true],
   

2. First Use Case Enable maintenance mode via CLI:

   php bin/console maintenance:enable
   

   Disable it with:

   php bin/console maintenance:disable
   

3. Where to Look First

   • Commands: php bin/console list → Filter for maintenance: commands.
   • Configuration: Check config/packages/arkanii_maintenance.yaml (auto-generated).
   • Twig Template: Override the default maintenance page at templates/maintenance.html.twig.

Implementation Patterns

Core Workflows

1. Toggle Maintenance Mode Use the console commands for quick toggling:

   # Enable with custom message
   php bin/console maintenance:enable --message="Under maintenance"
   
   # Disable
   php bin/console maintenance:disable
   

2. Conditional Maintenance Integrate with Symfony’s EventDispatcher to trigger maintenance dynamically:

   // src/EventListener/MaintenanceListener.php
   use Arkanii\MaintenanceBundle\Event\MaintenanceEvent;
   
   class MaintenanceListener {
       public function onMaintenance(MaintenanceEvent $event) {
           if ($event->isEnabled() && $event->getUser()->isAdmin()) {
               $event->setEnabled(false); // Allow admins
           }
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\MaintenanceListener:
           tags: ['kernel.event_listener', { event: 'arkanii.maintenance', method: 'onMaintenance' }]
   

3. Custom Templates Override the default Twig template by creating:

   templates/ArkaniiMaintenanceBundle/maintenance.html.twig
   

   Extend the base template with custom styling or logic.

4. API Maintenance Exclude API routes by configuring allowed_paths in config/packages/arkanii_maintenance.yaml:

   arkanii_maintenance:
       allowed_paths:
           - ^/api/
   

Integration Tips

• Laravel-Symfony Bridge: Use Symfony’s HttpKernel in Laravel via symfony/http-kernel to leverage this bundle.
• Environment-Based: Enable maintenance only in staging/production:

  # config/packages/arkanii_maintenance.yaml
  arkanii_maintenance:
      enabled: '%kernel.environment% == "prod"'
  

• Database Migrations: Store maintenance state in a DB table (extend the bundle or use a middleware to sync).

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear Symfony’s cache after enabling/disabling maintenance:

     php bin/console cache:clear
     

   • If using Varnish/Nginx, ensure cache headers (X-Symfony-Debug-Token) are respected.

2. Route Overrides

   • The bundle adds a maintenance route. Avoid naming conflicts with existing routes.

3. Twig Auto-Reload

   • Custom templates may not auto-reload during development. Restart the dev server after changes:

     php bin/console server:restart
     

4. IP Whitelisting

   • The bundle lacks built-in IP whitelisting. Implement via middleware:

     // src/Middleware/AllowMaintenanceForIPs.php
     public function handle(Request $request, Closure $next) {
         if (in_array($request->ip(), ['192.168.1.1', '127.0.0.1']) && $this->maintenance->isEnabled()) {
             $this->maintenance->setEnabled(false);
         }
         return $next($request);
     }
     

Debugging

• Check Status Use the maintenance:status command to verify mode:

  php bin/console maintenance:status
  

• Logs Enable debug mode (APP_DEBUG=1) to log maintenance events in var/log/dev.log.

Extension Points

1. Custom Events Extend the MaintenanceEvent to add metadata (e.g., reason, scheduledUntil):

   // src/Event/MaintenanceCustomEvent.php
   class MaintenanceCustomEvent extends MaintenanceEvent {
       private $scheduledUntil;
   
       public function __construct(bool $enabled, string $message, \DateTime $scheduledUntil) {
           parent::__construct($enabled, $message);
           $this->scheduledUntil = $scheduledUntil;
       }
   }
   

2. Middleware Integration Use the bundle’s MaintenanceChecker service in custom middleware:

   use Arkanii\MaintenanceBundle\MaintenanceChecker;
   
   class CustomMaintenanceMiddleware {
       public function __construct(private MaintenanceChecker $checker) {}
   
       public function handle(Request $request, Closure $next) {
           if ($this->checker->isEnabled()) {
               return new Response('Custom maintenance message', 503);
           }
           return $next($request);
       }
   }
   

3. Configuration Overrides Dynamically override settings via environment variables:

   # .env
   MAINTENANCE_MESSAGE="System upgrade in progress"
   MAINTENANCE_ENABLED="true"
   
   # config/packages/arkanii_maintenance.yaml
   arkanii_maintenance:
       message: '%env(MAINTENANCE_MESSAGE)%'
       enabled: '%env(bool:MAINTENANCE_ENABLED)%'
   

Pro Tips

• Scheduled Maintenance Combine with Symfony’s CronExpression to auto-disable after a duration:

  // src/Command/ScheduledMaintenanceCommand.php
  use Symfony\Component\Cron\CronExpression;
  
  class ScheduledMaintenanceCommand extends Command {
      protected function execute(InputInterface $input, OutputInterface $output) {
          $maintenance = $this->getContainer()->get('arkanii_maintenance.maintenance');
          if ($maintenance->isEnabled() && CronExpression::create('0 10 * * *')->isDue()) {
              $maintenance->disable();
          }
      }
  }
  

• Multi-Environment Use %kernel.environment% to tailor messages per environment:

  arkanii_maintenance:
      message: >
          %kernel.environment% == 'prod' ? 'Production maintenance' : 'Staging work in progress'