Weave Code
Symfony Maintenance Bundle Laravel Package
in-sys/symfony-maintenance-bundle
A lightweight Symfony bundle for enabling maintenance mode. It lets you show a custom maintenance page, control who can access the app during downtime, and toggle maintenance from the console or configuration—ideal for planned upgrades, deployments, and preventing users from seeing raw errors.
Symfony Maintenance Bundle gives your Symfony application a clean, configurable maintenance mode. When enabled, incoming requests are intercepted and served a friendly maintenance page, while privileged users or allow-listed paths can keep working. Configuration is handled through simple bundle settings, so you can toggle maintenance without redeploying.
- Configurable maintenance page with custom templates
- IP and path allow-listing for admins and health checks
- Event-driven activation via kernel listeners
- CLI/console commands to enable or disable maintenance quickly
- Framework-native integration with minimal setup
Frequently asked questions about Symfony Maintenance Bundle
- Can I use in-sys/symfony-maintenance-bundle in a Laravel application?
- No. It is a Symfony bundle that integrates through Symfony's DependencyInjection extension and a kernel.request event listener, primitives Laravel does not expose. Laravel already provides native maintenance mode through php artisan down and php artisan up, including bypass secrets, Retry-After headers, and pre-rendered views. Adopting the bundle directly would require a bridge layer that is more work than porting the small concept.
- How do I install in-sys/symfony-maintenance-bundle?
- Install it with Composer using composer require in-sys/symfony-maintenance-bundle, then register the bundle in your Symfony application's bundles.php or config/bundles.php as described in the README. Configure the authorized IP addresses in the bundle configuration. The package exposes console commands for toggling maintenance mode rather than Laravel Artisan commands.
- What console commands does this bundle provide for maintenance mode?
- The bundle provides two Symfony console commands to place the site into maintenance mode and bring it back out. The overview does not list their exact names, so check the README or run php bin/console list to confirm them in your installed version. They are Symfony console commands, not php artisan down or php artisan up.
- Does this package work with Laravel 10 or Laravel 11?
- No. The package targets Symfony 5.4 through 6 and does not ship a Laravel service provider, facade, or auto-discovery metadata. Laravel 10 and 11 applications should use the framework's native php artisan down and php artisan up commands. A Laravel adapter would be custom code, not something this package provides.
- What is the Laravel equivalent of this Symfony maintenance bundle?
- Laravel has built-in maintenance mode via php artisan down and php artisan up. The down command supports a secret bypass cookie with --secret, a Retry-After header with --retry, and a custom pre-rendered view with --render. For most Laravel applications this native tooling closes the same functional gap with no third-party dependency.
- How does IP whitelisting work with this Symfony maintenance bundle?
- The bundle lets you authorize certain IP addresses stored in its configuration, so those clients bypass the maintenance page and see the application. You need to configure trusted proxies correctly if your Symfony app sits behind a load balancer or reverse proxy, or the recorded client IP may be wrong. Test the bypass from allowed and disallowed networks before relying on it in production.
- Which Symfony and PHP versions are supported by in-sys/symfony-maintenance-bundle?
- The package overview describes a Symfony 5.4 through 6 bundle, while the technical assessment notes a narrower Symfony 6.4/7 window and PHP 8.1+ alignment. Verify the actual composer.json constraints for symfony/http-kernel and PHP before installing, because a Symfony constraint can force an unwanted framework upgrade. Also check the release and tag history rather than relying on the stated release date.
- Can I customize the 503 maintenance page or return JSON for API clients?
- The overview only guarantees a 503 status page for users; it does not document content negotiation for HTML, JSON, or health-check endpoints. In Symfony you can typically override the maintenance template, but confirm the bundle's actual rendering path and response headers in the source or README. If your API clients need JSON 503 responses, test that behavior explicitly or add your own listener.
- Is in-sys/symfony-maintenance-bundle production-ready and actively maintained?
- The assessment flags a single maintainer, zero dependents, and a one-star sustainability rating, so the bus factor is one. It is MIT licensed, which means you can fork it, but you inherit the maintenance burden. Review lock-file semantics and any bypass-secret handling before production use, especially fail-open or stale-lock behavior. For a Laravel-primary stack, do not adopt it as a runtime dependency.
- What alternatives should I consider instead of this bundle for Laravel maintenance mode?
- For Laravel, start with native php artisan down and php artisan up; add --secret, --retry, and --render as needed. If you need per-tenant toggling, shared state across multiple nodes, or CMS-rendered maintenance pages, build a small internal MaintenanceMode contract with a native Laravel driver. For Symfony services, this bundle is a legitimate one-line install, but keep it behind an adapter so the vendor remains swappable. A custom middleware and Artisan command pair is usually only a one-to-two-day port.
Weaver
How can I help you explore Laravel packages today?