Maintenance Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Aligns with Symfony/Laravel ecosystem (via Symfony bundles) for maintenance mode, leveraging HTTP 503 responses and static HTML fallbacks—ideal for load-balanced deployments.
  • Lightweight (no heavy dependencies) and focused on a single, well-defined use case (maintenance mode).
  • Supports Symfony 4.4–6.1 (and older versions via version pinning), making it adaptable to legacy Laravel/Symfony apps via Symfony Bridge or standalone Symfony components.
  • MIT license enables easy adoption without legal barriers.

• Cons:

  • Laravel-specific gap: Primarily designed for Symfony; Laravel integration requires abstraction (e.g., middleware or event listeners) to mimic Symfony’s Kernel/EventDispatcher.
  • Stale maintenance: Last release in 2016 raises concerns about compatibility with modern PHP/Laravel (e.g., no PHP 8.2+ support, no Symfony 7.x validation).
  • Limited features: Only provides static HTML + 503 responses; lacks dynamic maintenance pages, user whitelisting, or granular route control (common in modern tools like laravel-debugbar or spatie/laravel-maintenance-mode).

Integration Feasibility

• Symfony Apps: Direct drop-in via composer require (tested for SF 4.4–6.1).
• Laravel Apps: Requires wrapper layer to adapt Symfony’s EventDispatcher/Kernel patterns:
  • Option 1: Use Symfony Bridge (symfony/http-kernel) to integrate the bundle as a middleware.
  • Option 2: Reimplement core logic (503 responses + static files) in Laravel middleware (e.g., Illuminate\Http\Middleware).
  • Option 3: Fork/modify the bundle to use Laravel’s Events and ServiceProvider patterns.
• Monolithic vs. Microservices:
  • Ideal for monolithic Symfony/Laravel apps with load balancers.
  • Less suitable for microservices (where service mesh/ingress controllers like Nginx/Traefik handle 503s natively).

Technical Risk

Key Questions

1. Why not use existing Laravel packages (e.g., spatie/laravel-maintenance-mode)?
   • Tradeoff: Spatie is actively maintained but lacks Symfony integration. Corley offers consistency if using both stacks.
2. Can this replace Nginx/Traefik maintenance mode?
   • Tradeoff: Application-level control (e.g., dynamic messages) vs. infrastructure-level (faster, no PHP overhead).
3. How will we handle legacy Symfony 3.x/Laravel 5.x?
   • Tradeoff: Version pinning (^0.2) may introduce security risks; assess if upgrade is feasible.
4. What’s the fallback if the bundle fails?
   • Risk: Static file serving could break if web server misconfigures 503 responses.
5. Will this integrate with our CI/CD?
   • Example: Trigger maintenance mode via GitHub Actions or deploy hooks.

Integration Approach

Stack Fit

Migration Path

1. Symfony Apps:

   • Add to composer.json (version pinned to target Symfony/PHP).
   • Register bundle in config/bundles.php (SF Flex) or AppKernel.php (legacy).
   • Configure maintenance.html.twig in templates/ and set CORLEY_MAINTENANCE_ENABLED=true in .env.
   • Validation: Test 503 responses with curl -I http://app.url.

2. Laravel Apps:

   • Option A: Middleware Wrapper (Recommended):

     // app/Http/Middleware/MaintenanceMiddleware.php
     namespace App\Http\Middleware;
     use Closure;
     use Symfony\Component\HttpKernel\EventListener\MaintenanceListener;
     use Symfony\Component\HttpKernel\KernelEvents;
     
     class MaintenanceMiddleware extends \Illuminate\Foundation\Http\Middleware\MaintenanceMode
     {
         public function handle($request, Closure $next)
         {
             if ($this->isDownForMaintenance($request)) {
                 return response()->view('maintenance', [], 503);
             }
             return $next($request);
         }
     }
     

   • Option B: Event Listener:
     • Dispatch a MaintenanceEvent in Laravel and listen for it (requires adapting Symfony’s MaintenanceListener).
   • Option C: Fork the Bundle:
     • Replace Symfony\Component\HttpKernel\KernelInterface with Laravel’s Illuminate\Contracts\Http\Kernel and adapt events.

3. Hybrid Symfony/Laravel:

   • Use the bundle in Symfony microservices; replace with middleware in Laravel services.

Compatibility

• Symfony: High (tested versions); low for unsupported versions.
• Laravel: Medium (requires adaptation); higher with middleware approach.
• PHP Extensions: None (pure PHP).
• Database: None (static files only).

Sequencing

1. Pre-Integration:
   • Audit Symfony/Laravel versions to select correct corley/maintenance-bundle version.
   • Design static maintenance.html template (place in resources/views/ for Laravel or templates/ for Symfony).
2. Integration:
   • Symfony: Register bundle + configure .env.
   • Laravel: Implement middleware or event listener.
3. Testing:
   • Validate 503 responses with curl -I.
   • Test whitelisted routes (if extended).
   • Load test static file serving under traffic.
4. Deployment:
   • Enable via feature flag or deploy hook (e.g., php artisan maintenance:enable equivalent).
   • Monitor logs for 503 errors during cutover.

Operational Impact

Maintenance

• Symfony:
  • Bundle updates may require Symfony version alignment (risky due to age).
  • Static templates are easy to update but require redeploy.
• Laravel:
  • Custom middleware/event listeners need manual updates if Corley’s internals change.
  • No built-in CLI tools (unlike spatie/laravel-maintenance-mode).
• Shared Responsibilities:
  • Web server must respect 503 responses (e.g., Nginx fastcgi_intercept_errors).
  • CDN must cache static maintenance pages (configure Cache-Control: public, max-age=3600).

Support

• Pros:
  • Simple static file serving; minimal moving parts.
  • MIT license allows internal modifications.
• Cons:
  • No vendor support: Community/stars are negligible (22 stars, last release 2016).
  • Debugging: Issues may stem from Symfony/Laravel integration gaps.
• Workarounds:
  • Monitor for 503 loops (e.g., recursive maintenance checks).
  • Log maintenance mode activations/deactivations for auditing.

Scaling

• Performance:
  • Static HTML serving is O(1); no PHP overhead after initial request.
  • Load balancers will drain traffic efficiently (503 is standard).
• Horizontal Scaling:
  • Works seamlessly with Kubernetes (pods marked `Un