Maintenance Bundle Laravel Package

Getting Started

Before installing anything, confirm what you're actually looking at: nicolassing/maintenance-bundle is a republished pointer to the CorleyMaintenanceBundle repository, which is a Symfony bundle, not a Laravel package. Check its composer.json — you'll see "type": "symfony-bundle" and a Corley\MaintenanceBundle\CorleyMaintenanceBundle class. There is no laravel/framework dependency, no service provider auto-discovery, and no middleware. If you're on Laravel, composer require will install files that never execute.

Where to look first, if you're evaluating it seriously:

1. CorleyMaintenanceBundle.php — the bundle class (how it registers services).
2. EventListener/ or Listener/MaintenanceListener.php — the request listener that intercepts traffic.
3. DependencyInjection/Configuration.php — the real config surface (IPs, template, flag path, status code).
4. Command/ — the toggle commands (commonly corley:maintenance:enable / :disable).

Your first use case in a Laravel shop is not this package — it's php artisan down. The modern Laravel command already covers the same ground: --render=errors::503 for a custom view, --secret="..." for a bypass URL, --allow=1.2.3.4 for IP allowlisting, --retry=60 for the Retry-After header, and --redirect for redirecting instead of serving a page. Reach for the Corley bundle only if you own a Symfony service (or a shared monorepo) that needs this behavior.

Implementation Patterns

Symfony-native usage (the only mode this bundle supports). Enable it in AppKernel / bundles.php, then configure under the corley_maintenance root key: an enable flag, a template path, an IP allowlist, and a flag/lock file path. The listener hooks kernel.request and short-circuits with a 503 response before routing or controllers run. Toggle via the console commands in your deploy script.

Translate the listener pattern into Laravel. The bundle's core idea — a high-priority kernel listener that returns a maintenance response before anything else — maps cleanly to a global middleware registered with the highest priority:

// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->prepend(\App\Http\Middleware\MaintenanceMode::class);
})

Your middleware can read a config flag, compare $request->ip() against an allowlist, honor a secret token from the session or query string, and return response()->view('errors.503', status: 503)->header('Retry-After', 60). This is the same architecture as the bundle without dragging in Symfony's HttpKernel, EventDispatcher, and Request/Response classes.

Deployment workflow. The pattern the bundle is designed for: enable maintenance → run migrations / cache warm / symlink release → disable. In Laravel that's artisan down --secret=... --allow=... before the deploy and artisan up after. Use --secret to keep a bypass URL active so internal teams and health checks can verify the new release before opening the gates.

Custom maintenance page. The bundle exposes a Twig template override; Laravel's equivalent is --render=errors::503 pointing at a Blade view. Keep the view dependency-free — no DB queries, no session reads, no auth — because the database may be the exact thing that's down.

IP allowlist and secret bypass. Both features exist in the bundle (ips config + a bypass path); Laravel mirrors them with --allow and --secret. Prefer the secret URL over IP allowlisting when traffic goes through a CDN or load balancer, since $request->ip() may be the proxy address unless TrustProxies is configured correctly.

Gotchas and Tips

The framework mismatch is the headline. A Symfony bundle cannot be auto-discovered by Laravel, and kernel.request has no equivalent in Laravel's HTTP lifecycle. Any attempt to bridge it means manually instantiating the listener and wiring Symfony's event dispatcher — at which point you've pulled in a large slice of Symfony to reproduce 30 lines of middleware.

Package identity and trust. The repo name is CorleyMaintenanceBundle but the package name is nicolassing/maintenance-bundle, with 0 stars and 0 dependents. That's a personal republish, not the canonical distribution. Verify what you're installing with composer show -a nicolassing/maintenance-bundle, and if you're on Symfony, prefer corley/maintenance-bundle upstream directly.

Listener priority matters. The interceptor must fire before routing, auth, and CSRF. If it runs late, users hit a 500 (missing route, auth redirect loop) instead of the intended 503. In Laravel, prepend your middleware; in Symfony, confirm the tag priority is high (e.g. kernel.request priority above 32).

Static assets bypass the app entirely. Nginx/Apache and your CDN serve CSS, JS, and images before PHP runs. The maintenance page often renders unstyled because its assets are 404s. Serve a static maintenance page at the web-server level, or inline all CSS in the 503 view.

Return 503 with Retry-After. Search engines and load balancers need both to treat this as temporary. A 200 or 302 maintenance page gets indexed.

Don't store the flag in the database. The DB may be down for exactly the operation you're performing. Use a file (the bundle's lock-file approach) or an env var.

Clear the config cache after toggling. In Symfony, cache:clear/cache:warmup can bake the flag into the compiled container. In Laravel, config:cache will freeze any config-based flag — read the flag at runtime, not from a cached config value.

Sessions and CSRF. If the maintenance view extends an authenticated layout, it will try to resolve the user and blow up when the session store is unavailable. Keep the 503 view completely standalone.

Extension points. Symfony-side you can override the Twig template, decorate the listener, or swap the status code. On the Laravel side, the equivalent extension points are the errors.503 view, the middleware's allowlist logic, and the secret-token check — keep each of those isolated so a future swap back to artisan down is a one-line bootstrap/app.php change.