Maintenance Bundle Laravel Package

Getting Started

• Install with composer require mathis-vincent/maintenance-bundle and check the package README for the current configuration keys before wiring anything into your app.
• Look first at the bundle's configuration reference and the bypass-cookie settings. Release 1.1.2 specifically corrects bypass-cookie behaviour, so confirm the documented cookie name, path, domain, and secret handling rather than copying older examples.
• Note the integration context: this is a Symfony-style bundle, not a Laravel-native package. In a Laravel app, check whether it ships a Laravel service provider or whether you need to bridge its maintenance check into middleware yourself.
• First use case: put an application into maintenance mode during a deploy while allowing internal users, QA, or stakeholders to continue browsing via a bypass cookie. The 1.1.2 fix is directly relevant if that is your primary workflow.
• If you are evaluating this purely for Laravel day-to-day use, compare against Laravel's built-in php artisan down --secret="...", which provides a similar cookie-based bypass with no bridge code.

Implementation Patterns

• Deploy-window maintenance: enable maintenance mode before migrations or asset compilation, serve a custom 503 page, and disable it after smoke tests pass.
• Bypass cookie for stakeholders: issue the bypass cookie only to trusted users. The expected flow is: request arrives → maintenance check runs → if a valid bypass cookie is present, continue to the application; otherwise render the maintenance response.
• Health-check and webhook exclusions: keep load-balancer health endpoints, status pages, and inbound webhooks out of the maintenance response. In Laravel, this usually means a middleware priority list or route exclusions.
• Custom maintenance response: return HTTP 503 with a Retry-After header and a branded maintenance page. Avoid returning 200 for maintenance responses, as it hides outages from monitoring.
• Configuration-driven toggling: drive maintenance state from an environment variable or config flag so it can be flipped without a code deploy. Cache the config in production and clear it when toggling.
• Version pinning: pin to ^1.1.2 if you depend on bypass-cookie behaviour. The 1.1.2 release is a patch-level correction, so it should be a safe upgrade from 1.1.1, but verify your bypass flow after upgrading.
• Laravel bridge pattern: if adapting the bundle, wrap the maintenance check in a global middleware registered after session/cookie middleware so the bypass cookie is readable, and before authentication so unauthenticated requests are handled consistently.

Gotchas and Tips

• Bypass cookie correction in 1.1.2: if bypass cookies were unreliable on 1.1.1 or earlier, upgrade and retest. Clear existing cookies, config cache, and any cached HTTP responses before concluding the fix works.
• Cookie scope matters: a cookie set for the wrong path, domain, or Secure/SameSite combination will silently fail the bypass. Verify the cookie in the browser dev tools and confirm it is sent on the request that should bypass maintenance.
• Symfony bundle vs Laravel: Laravel package auto-discovery will not register a Symfony bundle. Expect to add manual wiring or use a different package if you want zero-integration Laravel support.
• Do not depend on the database during maintenance: the maintenance check itself should not require the database, cache, or queue if those are the systems being worked on. Prefer file/config-based state for the maintenance flag.
• Secret leakage: never put the bypass secret in URLs that end up in logs, referrers, or analytics. Prefer a cookie set out-of-band over a query-string secret.
• Monitoring blind spots: excluding too many paths from maintenance mode can mask a real outage. Keep exclusions narrow and documented.
• Extension points to inspect: custom maintenance templates, IP allowlists, custom status codes, and event/listener hooks around enabling and disabling maintenance mode. These are the usual places to adapt behaviour without forking.
• Debugging checklist: confirm middleware/bundle order, confirm the bypass cookie is read before the maintenance response is rendered, check config cache, and compare behaviour against the 1.1.1 → 1.1.2 changelog if upgrading.