Under Maintenance Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cvr/under-maintenance-bundle
   

   Register the bundle in config/bundles.php:

   Cvr\UnderMaintenanceBundle\UnderMaintenanceBundle::class => ['all' => true],
   

2. Enable Maintenance Mode: Add to .env:

   MAINTENANCE=1
   MAINTENANCE_TOKEN=your_secure_token_here
   

3. First Use Case:

   • Place your site under maintenance by setting MAINTENANCE=1.
   • Access the site with the token to bypass maintenance:

     http://your-site.com?maintenance=your_secure_token_here
     

Implementation Patterns

Workflows

1. Temporary Maintenance Mode:

   • Useful for deployments or urgent fixes.
   • Enable via .env and disable post-deployment:

     sed -i 's/MAINTENANCE=1/MAINTENANCE=0/' .env
     

2. Custom Maintenance Pages:

   • Override the default Twig template by creating:

     templates/bundles/UnderMaintenanceBundle/maintenance.html.twig
     

   • Clear cache afterward:

     php bin/console cache:clear
     

3. Token-Based Access Control:

   • Distribute the token securely to authorized users (e.g., team members).
   • Rotate tokens periodically for security.

4. Integration with Deployment Scripts:

   • Automate maintenance mode toggling in CI/CD pipelines:

     # Enable maintenance before deployment
     sed -i 's/MAINTENANCE=0/MAINTENANCE=1/' .env
     git add .env && git commit -m "Enable maintenance mode"
     
     # Disable after deployment
     sed -i 's/MAINTENANCE=1/MAINTENANCE=0/' .env
     git add .env && git commit -m "Disable maintenance mode"
     

Laravel-Specific Tips

• Service Provider Binding: If using Laravel’s service container, bind the bundle’s services explicitly in AppServiceProvider:

  $this->app->bind('under_maintenance', function () {
      return new \Cvr\UnderMaintenanceBundle\Service\MaintenanceService();
  });
  

• Route Middleware: Extend functionality by creating a custom middleware to check maintenance status:

  namespace App\Http\Middleware;
  
  use Closure;
  use Symfony\Component\HttpFoundation\Request;
  
  class MaintenanceCheck
  {
      public function handle(Request $request, Closure $next)
      {
          if (config('under_maintenance.enabled') && !$request->query->has('maintenance')) {
              return redirect()->route('maintenance.page');
          }
          return $next($request);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Cache Invalidation:

   • Forgetting to clear the cache (php bin/console cache:clear) after template overrides will result in the old template being displayed.

2. Token Exposure:

   • Hardcoding tokens in .env is fine, but avoid logging or committing them to version control.
   • Use environment variables or a secrets manager for production.

3. Symfony vs. Laravel Quirks:

   • The bundle is Symfony-focused. In Laravel, ensure the config/bundles.php file exists (create it if missing) and is properly formatted.
   • Laravel’s routing system may conflict with Symfony’s event listeners. Test thoroughly after integration.

4. Template Override Path:

   • The template path must be exact:

     templates/bundles/UnderMaintenanceBundle/maintenance.html.twig
     

   • Case sensitivity matters on Linux-based systems.

5. Token Validation:

   • The bundle does not validate token complexity. Use a strong token (e.g., 32+ chars, alphanumeric + symbols) to mitigate brute-force risks.

Debugging

• Check Maintenance Status: Verify the .env values are loaded correctly:

  php bin/console debug:config under_maintenance
  

  Should output:

  enabled: true
  token: your_secure_token_here
  

• Template Not Updating: Ensure the template file exists and permissions allow reading. Check Symfony’s cache directory (var/cache/dev/) for compiled templates.

• Token Bypass Failing: Confirm the query parameter is named exactly maintenance (case-sensitive in Symfony).

Extension Points

1. Custom Logic: Extend the bundle by overriding the MaintenanceListener class:

   namespace App\EventListener;
   
   use Cvr\UnderMaintenanceBundle\Event\MaintenanceEvent;
   use Symfony\Component\HttpKernel\Event\GetResponseEvent;
   
   class CustomMaintenanceListener
   {
       public function onMaintenance(GetResponseEvent $event)
       {
           $request = $event->getRequest();
           if ($request->query->get('maintenance') === 'custom_token') {
               // Custom logic (e.g., redirect to a specific page)
           }
       }
   }
   

   Register the listener in config/services.yaml (Symfony) or AppServiceProvider (Laravel).

2. Dynamic Tokens: Generate tokens dynamically (e.g., via API) by overriding the MaintenanceService:

   namespace App\Service;
   
   use Cvr\UnderMaintenanceBundle\Service\MaintenanceService as BaseService;
   
   class CustomMaintenanceService extends BaseService
   {
       public function getToken()
       {
           return $this->generateSecureToken(); // Custom logic
       }
   }
   

3. Multi-Token Support: Allow multiple tokens by modifying the listener to check against an array:

   $validTokens = ['token1', 'token2', 'token3'];
   if (in_array($request->query->get('maintenance'), $validTokens)) {
       // Allow access
   }