Bundle Health Check Laravel Package

Getting Started

This release (2.3.3) is a patch. Two changes only: a CI secret reference fix (no runtime impact) and Symfony 7.4 support added to the compatibility matrix. There are no breaking changes, no deprecations, and no new public API. Upgrading from 2.3.2 is safe; the only reason to move forward deliberately is if you are running Symfony 7.4 (or planning to), which 2.3.3 now permits.

• composer require oat-sa/bundle-health-check (or bump your existing constraint to ^2.3.3). Verify the PHP constraint in the package's composer.json before upgrading — Symfony 7.4 usually implies PHP 8.2+.
• Register the bundle in your kernel bundle list (config/bundles.php for a standard Symfony-style app; TAO-based installs register via the bundle manifest in the extension config). Confirm the registration path against the package README for your platform version — this differs between TAO generations.
• Look first at: the bundle's DependencyInjection/Configuration.php (what config keys actually exist), the HealthCheck/checker classes (what is measured by default), and the routing definition (what path the endpoint is exposed on).
• First use case: expose the health endpoint and point a single uptime monitor or load-balancer probe at it. Then, before adding anything custom, hit it manually with curl -i and read the JSON payload — the response shape tells you what the bundle already checks for free (typically DB connectivity, filesystem writability, and cache) before you write your own checks.

Implementation Patterns

• Readiness gate in CI/CD. Run the health endpoint as a post-deploy smoke test before switching traffic or running migrations. Treat a non-2xx response (or a payload with a failed check) as a failed deploy step.
• Custom checks as tagged services. The idiomatic extension point is a class implementing the bundle's check interface, registered with the bundle's service tag via autoconfigure: true or an explicit tags: entry. Keep each check small and side-effect free — one dependency per check, so a failure names the culprit.
• Separate liveness from readiness. If you run Kubernetes or an orchestrator, do not point the deep check (DB, queue, external APIs) at the liveness probe. A transient DB blip will restart a perfectly healthy container. Use a shallow endpoint for liveness and the full bundle output for readiness/alerting.
• Aggregate for alerting rather than per-check alerts. Emit the whole payload to your monitoring stack (blackbox exporter, Datadog HTTP check, uptime service) and alert on the aggregate status. Per-check alert rules multiply quickly as the bundle grows.
• Keep the endpoint behind a boundary. Restrict by IP allowlist or a shared-secret header at the web-server/reverse-proxy layer. This is a package concern the bundle cannot solve for you.
• Local development. Wire the check into your existing test suite as a single functional test that boots the kernel and asserts a 200 — cheap, and it catches service-wiring regressions that unit tests miss.

Gotchas and Tips

• The 2.3.3 diff is not a feature release. Do not go looking for new config keys or endpoint options; there are none. If you need a changelog entry for audit purposes, cite "Symfony 7.4 compatibility" only.
• Symfony 7.4 support is a constraint widening, not a rewrite. If you are on an older Symfony, upgrading gains you nothing and costs you a dependency resolution. Pin to 2.3.2 until you actually move to 7.4 if you want a minimal diff.
• Tagged services need a container rebuild. After adding a custom check, a stale compiled container will silently omit it — the endpoint returns 200 and you assume the check passed. Clear/warm the cache and verify with debug:container --tag=<bundle tag> that your service is actually registered.
• Silent pass is the classic failure mode. A check that throws inside its own try/catch, or one whose timeout fires, can be reported as "unknown" or omitted entirely. Assert on the contents of the payload in tests, not just the HTTP status code.
• Timeouts are your responsibility. Any check that reaches a database or remote HTTP service will eventually hang. Set explicit connect/read timeouts inside the check and cap total endpoint latency at the proxy so a wedged dependency does not take down your load balancer's health probe too.
• Debugging a failing check: run the check class in isolation from a console command or php -r bootstrap before blaming the bundle. Nine times out of ten the failure is credentials, a missing PHP extension, or a permissions issue on a writable directory — not the bundle.
• CI secret handling (from this release). The SONAR_HOST_URL fix is internal to the project's own pipeline; it changes nothing for consumers. But it is a reminder: if you vendor or fork this package, grep your own workflows for hardcoded host URLs and secrets before publishing.
• Extension points to remember: custom check classes + service tags, bundle configuration for enabling/disabling individual checks, and the response formatter (if the bundle lets you swap it) for matching your monitoring tool's expected JSON schema.