Maintenance Mode Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — the repo is NorthernMaintenanceModeBundle, and the naming convention (*Bundle, northernco/...-bundle) is a giveaway. If you're a Laravel developer looking for php artisan down, this is not the package for you; look at laravel/framework's built-in maintenance mode or spatie/laravel-maintenance instead.

If you're in a Symfony app:

1. composer require northernco/maintenance-mode-bundle
2. Register the bundle in config/bundles.php:

   NorthernCo\MaintenanceModeBundle\NorthernMaintenanceModeBundle::class => ['all' => true],
   

3. Publish/configure the bundle config (typically under config/packages/northern_maintenance_mode.yaml). Expect keys for enabled state, HTTP status code, retry-after header, allow-listed IPs, and a template/redirect target.
4. First use case: flip the bundle on via config or a toggle mechanism and confirm your app returns a 503 with a custom page instead of an unhandled error.

Where to look first: the bundle's Resources/config/ (service definitions) and its event subscriber / kernel listener — that's where the 503 behavior and IP bypass logic will actually live. There is no meaningful public documentation signal from a 1-star, 0-dependent package; read the source.

Implementation Patterns

Because the package is essentially unproven, treat the following as the patterns a maintenance-mode bundle should support, and verify each against the source before depending on it:

• Global toggle via config + env var. Wire enabled: '%env(bool:MAINTENANCE_MODE)%' so ops can flip it per-environment without a deploy. This is the single most valuable integration point — confirm the bundle exposes it.
• IP allow-list for staged rollouts. You'll want your office/VPN ranges exempted so you can verify the maintenance page while the public sees 503. Look for an allowed_ips config key; if absent, fork or override the listener.
• Custom response page. Point the bundle at a Twig template (templates/maintenance.html.twig) so the 503 body matches your brand and includes a Retry-After header hint.
• CLI toggle (or roll your own). If the bundle ships a command like app:maintenance:on|off, use it from deploys; if not, a one-line cache:clear after editing the env var is your fallback. Consider a small custom command that toggles a marker file — it's often more reliable than config edits under deploy automation.
• Kernel-level short-circuit. The correct integration is a kernel.request listener with a high priority (before routing/auth) returning a Response(503, ...). Verify the bundle's listener priority; if it runs after the firewall, users hit auth errors before seeing maintenance.
• Healthcheck exemption. Exempt /healthz or /metrics paths so your load balancer doesn't pull instances out of rotation because you put them in maintenance.

Typical day-to-day workflow with a bundle like this: enable in staging for a schema-migration window → verify via allow-listed IP → flip the env var in production → run migrations → flip back → cache:clear if config is cached.

Gotchas and Tips

• This package is essentially unvetted. 1 star, 0 dependents, one release. Do not ship it to production without reading every file. For a ~50-line behavior (return 503 unless IP whitelisted), you may be better off writing a 30-line kernel.request subscriber yourself — you'll get better test coverage and no supply-chain risk.
• Config cache is the #1 debugging trap. Symfony caches compiled config and service definitions. After changing the enabled flag or the IP list, run bin/console cache:clear (in the right env, --env=prod) or your change silently does nothing. This trips up almost everyone the first time.
• Asset and sub-request bypass. The listener may also catch _profiler, _wdt, or asset requests. Confirm those paths are excluded, otherwise the Symfony debug toolbar and your maintenance page's own CSS 503.
• HTTP status semantics. Maintenance should be 503 with Retry-After, not 200 or 404. Search engine crawlers and CDNs (Cloudflare, Fastly) treat these very differently. Check the bundle sets the header correctly.
• CLI context. A kernel.request listener never fires for console commands — good, you want migrations and commands to run during maintenance. Don't "fix" this.
• Behind a reverse proxy / load balancer. The bundle sees the proxy's IP, not the client's. If IP allow-listing doesn't work, you need TrustedProxies / TrustedHeaders configured at the framework level — the bundle cannot solve this for you.
• Extension points to look for: an event like MaintenanceModeEnabledEvent, a configurable response factory, or a MaintenanceCheckerInterface you can decorate. If none of these exist, you'll be editing vendor code — a hard no for production.
• Alternatives worth benchmarking: symfony/framework-bundle's own framework.php_errors and a hand-rolled listener; scheb/maintenance-bundle (though similarly niche); or a generic 503 middleware in your public/index.php front controller. For Laravel, php artisan down --render="errors::503" --secret="..." covers nearly every use case this bundle would.
• Version pinning. With one release and no dependents, pin an exact version ("northernco/maintenance-mode-bundle": "1.0.0" not ^1.0) and commit the composer lock so a silent retag can't break you.