Weave Code
Maintenance Bundle Laravel Package
rich-id/maintenance-bundle
Maintenance bundle for Laravel/PHP apps that adds configurable maintenance mode so you can take your site offline gracefully. Customize the maintenance page, allow selected IPs or routes through, and control access without touching core code.
Provides a BackOffice page to manage the website locking, and a warning flag for user authorised to bypass the lock.
Frequently asked questions about Maintenance Bundle
- How do I put a Laravel app into maintenance mode with rich-id/maintenance-bundle?
- Install the package with Composer, then toggle maintenance mode with a single command or a config flag; the package intercepts incoming requests and serves a friendly placeholder page. Because the maintenance state is centralized, scheduled jobs and deploy scripts can continue to run while HTTP traffic is paused. Review the package config for the maintenance flag, custom page, status code, and optional IP allowlist before enabling it in production.
- Is rich-id/maintenance-bundle a Laravel package or a Symfony bundle?
- The overview describes a framework-agnostic core with integration hooks, but the v2.2.1 release notes mention upgrading sensio/framework-extra-bundle, a deprecated Symfony HTTP kernel bundle. Check whether that dependency is in require or require-dev: if it is require-dev and used only for the package's own test matrix, Laravel consumers are largely unaffected; if it is a runtime require, the package is Symfony-first and a poor fit for a Laravel app. Do not treat it as Laravel-native until that question is answered.
- How do I install and configure rich-id/maintenance-bundle in Laravel?
- Add the package with composer require rich-id/maintenance-bundle, then review its configuration for the maintenance toggle, custom placeholder page, HTTP status response, and optional IP allowlist. The core is framework-agnostic, so any service provider or integration hook needed for Laravel should be confirmed in the README before wiring it into your app. Pin an explicit version rather than a floating constraint so future dependency changes cannot arrive unannounced.
- Can I allow specific IP addresses to bypass maintenance mode?
- Yes, the package includes an optional IP allowlist so trusted users can bypass maintenance mode while everyone else sees the placeholder page. This is useful for QA teams, stakeholders, uptime monitors, and internal staff who need to verify the site during a deployment window. Configure the allowlist in the package config and test it in staging before relying on it in production.
- Does rich-id/maintenance-bundle work with Laravel 10 and Laravel 11?
- The provided overview does not state explicit Laravel version support, so validate against the exact Laravel versions in your estate, at minimum the current LTS and the previous major. Inspect composer.json for illuminate/* and php constraints, and check the lockfile diff after composer update --with-dependencies. If the package pulls Symfony kernel constraints transitively, confirm they overlap cleanly with the symfony/* components Laravel already ships.
- How do I customize the maintenance page and HTTP status code?
- The package supports a customizable maintenance page and configurable HTTP status responses, so you can serve a friendly placeholder instead of a raw error. Configure the view or template and the status code in the package config; for SEO-friendly maintenance, a 503 Service Unavailable with a Retry-After header is typically appropriate. Keep the page lightweight and avoid loading your full application stack if the package supports a static placeholder.
- Will maintenance mode block scheduled jobs and deploy scripts?
- The package is designed to centralize maintenance state so HTTP requests can be intercepted and served a placeholder while scheduled jobs and deploy scripts continue to run. That separation is the main reason to use it instead of a blunt web-server block. Confirm how your queue workers, cron entries, and deploy hooks integrate with the package's toggle, and test that they still execute during maintenance.
- What are the risks of the sensio/framework-extra-bundle dependency in v2.2.1?
- sensio/framework-extra-bundle is deprecated upstream, so a release that only bumps it is a supportability signal. If it is a runtime require, it adds dead weight or version pressure on symfony/* components that Laravel itself depends on; if it is require-dev, Laravel consumers are largely unaffected. Pin 2.2.1 explicitly, review the composer.lock diff, and watch for a future release that drops or replaces the bundle, which is where the real breaking change is likely to land.
- How should I test maintenance mode before enabling it in production?
- Test in staging by toggling maintenance mode through the config flag or command, then verify the placeholder page, HTTP status code, IP allowlist bypass, and that scheduled jobs still run. Add an integration test that hits a route and asserts the expected maintenance response, and run composer update --with-dependencies to confirm the lockfile changes are limited to the package and its subtree. Repeat the check against each Laravel version you support.
- Is rich-id/maintenance-bundle actively maintained, and what alternatives exist?
- The v2.2.1 release is a patch that only records an upgrade to an abandoned Symfony bundle, with no changelog detail, which is a documentation and supportability concern for a production dependency. Laravel's native php artisan down and php artisan up commands are the default alternative and support secret-based bypass and custom views; evaluate this package only if you need its framework-agnostic core or centralized toggle across non-Laravel services. Monitor the repository for a release that removes sensio/framework-extra-bundle.
Weaver
How can I help you explore Laravel packages today?