Weave Code
Symfony Health Check Bundle Laravel Package
macpaw/symfony-health-check-bundle
A Symfony bundle that adds configurable health check endpoints to your app, with built-in and custom checks for databases, cache, and other services. Expose readiness and liveness status for monitoring, load balancers, and Kubernetes.
A Symfony bundle that adds production-ready health check endpoints to your application. It aggregates configurable checks for critical dependencies and custom services, exposing a simple HTTP endpoint for load balancers, Kubernetes probes, and monitoring systems.
- Pluggable health checks via
HealthCheckInterfaceand service tags - Built-in checks for common infrastructure dependencies
- JSON responses with appropriate HTTP status codes
- Symfony DI integration for zero-config setup
- Kubernetes/Docker-friendly readiness and liveness probes
Frequently asked questions about Symfony Health Check Bundle
- Can I use macpaw/symfony-health-check-bundle in a Laravel application?
- No, not natively. macpaw/symfony-health-check-bundle is a Symfony bundle (type symfony-bundle) that registers through config/bundles.php, a DependencyInjection extension, a compiler pass for tagged checkers, and a kernel event subscriber that binds the route. Laravel runs none of that machinery, and the package ships no extra.laravel.providers entry and no service provider. Composer will install it into a Laravel app without error, which makes the failure mode silent rather than obvious.
- Why does the package install with Composer but no health route appears in Laravel?
- Because installing a package is not the same as integrating it. The bundle relies on Symfony's kernel to boot its extension and register routes; Laravel never triggers that lifecycle, so no health endpoint appears and no configuration is read. There is no auto-discovery hook for Laravel to find. Treat a clean composer require as evidence of nothing here.
- What Laravel versions does this health check bundle support?
- The package targets Symfony, not Laravel, so Laravel version support is effectively none: Laravel 10, 11 and 12 are all equally unsupported. Check its composer.json for the Symfony framework-bundle constraint if you are evaluating it for a Symfony service. If your goal is a Laravel health endpoint, choose a Laravel-native option instead.
- How do I install and configure this bundle in a Symfony app?
- Run composer require macpaw/symfony-health-check-bundle, enable it in config/bundles.php, configure the extension tree in your Symfony config, tag your checker services, and import the bundle's route. Setup is typically under an hour on a Symfony service. It is a reasonable standard there because the bundle handles discovery, aggregation and routing for you.
- Is there a Laravel alternative to this Symfony health check bundle?
- For Laravel, look at spatie/laravel-health, Laravel 11's built-in /up route, or a thin in-house controller that returns aggregate JSON with 200/503. Those give you the same response contract without dragging Symfony components into an Illuminate stack. If you already run APM agents or load balancer probes, check whether they cover readiness before adding anything.
- How do I return 200/503 aggregate health JSON in Laravel like this bundle does?
- Skip the bundle and implement the contract directly. Create a liveness route and a readiness route, run your checks through a collection of closures or checker classes, and return JSON with a 200 when everything passes and a 503 when anything fails. Match the response schema and status vocabulary the bundle uses so dashboards and alerts stay consistent across a mixed estate. This is the genuinely portable part of the package.
- How do custom checkers work, and can I reuse them in Laravel?
- In Symfony, a checker is a service implementing the bundle's checker interface and tagged so the compiler pass can collect it. In Laravel that discovery mechanism does not exist, so you would have to instantiate each checker manually inside a service provider and pass it to your own aggregator. At that point you have reimplemented the bundle's core value in-house and only the checker bodies survive, and only if they carry no container assumptions.
- Is it safe to expose the health endpoint publicly in production?
- Health payloads leak topology: database reachability, queue lag, dependency names and version strings. Keep the endpoint behind mesh or ingress restrictions rather than exposing it publicly, and avoid checks that touch write paths, run deep queries or introspect queues at probe frequency. Health endpoints sit on the critical path for orchestrators and load balancers, so a wrong check can cause restart loops or capacity drain.
- Is macpaw/symfony-health-check-bundle actively maintained?
- Activity exists, with the most recent release dated 2026-05-06, but the project has roughly 62 stars, zero dependents and single-vendor stewardship at MacPaw. There is no downstream validation or community backpressure, so bus factor is the dominant risk. The MIT license means you can read, fork or vendor it if you need to, but plan an owner for upgrades.
- How do I test a health endpoint that mirrors this bundle's response contract?
- Write a feature test that hits your health route and asserts a 200 plus the expected JSON keys, then force one dependency to fail and assert the 503 and the failing check name. Mock the checker layer rather than hitting a real database or queue in CI so the test stays fast and deterministic. Also assert the endpoint is unreachable without the expected network restrictions if that matters for your threat model.
Weaver
How can I help you explore Laravel packages today?