Maintenance Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require artgris/maintenance-bundle
   

2. Enable in config/packages/artgris_maintenance.yaml:

   artgris_maintenance:
       enable: true
       ips: ["127.0.0.1", "::1"]  # Allow local access
   

3. Clear cache (critical for prod):

   php bin/console cache:clear
   

4. Test: Visit your site—non-whitelisted IPs see the maintenance page (HTTP 503).

First Use Case

Deploy a new feature? Enable maintenance before pushing:

# Temporarily allow your IP (prod)
php bin/console cache:clear
# Then disable after deployment

Implementation Patterns

Workflows

1. Pre-Deployment Checklist:

   • Enable maintenance (enable: true).
   • Whitelist your IP + CI/CD server IPs.
   • Clear cache before deploying to prod.

2. Dynamic Maintenance Pages: Override templates/bundles/ArtgrisMaintenanceBundle/maintenance.html.twig to customize:

   {% extends "@ArtgrisMaintenance/maintenance.html.twig" %}
   {% block content %}
       <h1>{{ 'maintenance.title'|trans }}</h1>
       <p>{{ 'maintenance.message'|trans }}</p>
   {% endblock %}
   

   Tip: Use translation keys for multilingual support.

3. Environment-Specific Config: Use Symfony’s environment variables or %env() in artgris_maintenance.yaml:

   ips: ["%MAINTENANCE_WHITELIST_IPS%"]
   

4. API Maintenance: Extend the bundle to return JSON for API routes (see Gotchas for hooks).

Integration Tips

• CI/CD Pipelines: Add a step to enable maintenance before deploy and disable afterward.
• Database Migrations: Combine with a migration tool (e.g., Doctrine Migrations) to auto-enable maintenance before schema changes.
• Monitoring: Log maintenance activations/deactivations via Symfony’s event system (e.g., kernel.request listener).

Gotchas and Tips

Pitfalls

1. Cache Clearing:

   • Forgetting to clear cache in prod leaves maintenance enabled indefinitely.
   • Fix: Add a post-deploy hook (e.g., Deployer task) to clear cache.

2. IP Whitelisting:

   • Dynamic IPs (e.g., cloud load balancers) require manual updates or a more flexible solution (see Extension Points).
   • Tip: Use CIDR notation for ranges:

     ips: ["192.168.1.0/24"]
     

3. Dev Environment:

   • Maintenance is automatically disabled in dev—test locally with:

     enable: true
     ips: ["127.0.0.1"]
     

4. HTTP Status Code:

   • Default 503 may break SEO. Use 200 with a meta tag for crawlers:

     <meta name="robots" content="noindex">
     

Debugging

• Check if maintenance is active:

  php bin/console debug:config artgris_maintenance
  

• Bypass maintenance (dev only): Set enable: false or override the listener (see Extension Points).

Extension Points

1. Custom Logic: Override the MaintenanceListener to add conditions (e.g., time-based maintenance):

   // src/EventListener/CustomMaintenanceListener.php
   use Artgris\MaintenanceBundle\EventListener\MaintenanceListener;
   
   class CustomMaintenanceListener extends MaintenanceListener {
       public function isMaintenance(): bool {
           return parent::isMaintenance() && $this->isScheduledMaintenance();
       }
   }
   

   Register it in config/services.yaml:

   services:
       App\EventListener\CustomMaintenanceListener:
           tags: [kernel.event_listener, { event: kernel.request, method: onKernelRequest }]
   

2. API-Specific Responses: Extend the bundle to return JSON for API routes:

   {% if request.isXmlHttpRequest %}
       {{ { 'error': 'Service Unavailable', 'code': 503 }|json_encode|raw }}
   {% else %}
       {% include '@ArtgrisMaintenance/maintenance.html.twig' %}
   {% endif %}
   

3. Multi-Tenant Maintenance: Use a database-backed whitelist (e.g., tenants table) and override isAuthorized() in the listener.

Config Quirks

• Empty ips array: Maintenance affects all IPs (use ips: [] to disable for everyone).
• Case Sensitivity: IP addresses in ips are case-sensitive (use lowercase).
• Symfony 6+: Ensure config/packages/ is used (not config/bundles.php).