Healthcheck Bundle Laravel Package

Product Decisions This Supports

• Operational readiness / SLO instrumentation: A predictable GET/HEAD health endpoint is the contract your load balancers, Kubernetes probes, and uptime monitors depend on. This release makes that contract stronger by handling health requests on kernel.request at PHP_INT_MAX, i.e. before routing, security, channel, and locale listeners — health checks stop depending on firewall rules, locale negotiation, or route registration succeeding. That is a product reliability decision, not just a technical one: probe failures become genuine application-health signals instead of configuration noise.
• Build vs. buy for platform plumbing: Health endpoints are undifferentiated heavy lifting. The maintained surface area here is small (tagged boolean checks, failure logging, custom HTTP exceptions), which argues for buying/consuming rather than owning a bespoke controller and route in every service.
• Roadmap de-scoping: Removing the route layer and the direct Symfony Routing dependency is scope removal. Treat this as permission to delete internal healthcheck routes and any route-name-based URL generation (healthcheck.…) from downstream services — a cleanup item to schedule in the next maintenance window rather than new work to plan.
• Deployment/config contract: HEALTHCHECK_PATH is now read from the first present environment source at container compile time. This makes the path a build-time/deploy-time configuration decision with a documented default and literal-path normalization — product-relevant because changing it requires a container cache rebuild, which must be reflected in runbooks and release checklists.
• Feature flags / gating signal: Tagged boolean checks let you express "is feature X enabled and healthy" as part of the probe, keeping enablement decisions observable in the same place operators look first.

When to Consider This Package

Adopt when:

• You run Laravel/Symfony-style PHP services behind load balancers, Kubernetes, or external uptime monitoring and need a single, stable health endpoint.
• You want health checks that are immune to request-pipeline ordering — security middleware, locale/channel resolution, or route caching should not be able to make a healthy app look down.
• You need lightweight, composable health assertions (tagged boolean checks) plus structured failure logging and custom HTTP status codes.
• You prefer a narrow, private-internal controller with no public route surface to secure, document, or version.
• You are standardizing health checks across many services and want one configuration knob (HEALTHCHECK_PATH) with a documented default.

Look elsewhere when:

• You need a rich health API — per-dependency JSON payloads, readiness vs. liveness differentiation, metrics export, or dashboarding. This package deliberately keeps the controller internal and the surface minimal.
• You depend on named-route URL generation or bundle route imports. This is a breaking change in v1.1.0: previous bundle route imports are gone and named route-based URL generation is no longer provided. Any downstream code calling route('…healthcheck…') or importing the bundle's routes must be updated.
• You require runtime (per-request) mutability of the health path. The value is resolved at container compilation and needs HEALTHCHECK_PATH changes to be followed by a cache rebuild — dynamic, tenant-specific paths are out of scope.
• You need an actively evolving feature roadmap. Note the release cadence signal: v1.1.0 publishes the same commit as v1.0.1 under a requested minor version. Functionally this is a breaking setup change plus a renumbering, not a feature release. Plan upgrades as a chore with a migration note, not as a capability gain.

How to Pitch It (Stakeholders)

To executives: This is a small, low-risk infrastructure component that keeps our services' health endpoints accurate, so monitoring and autoscaling react to real outages rather than to middleware misconfiguration. The v1.1.0 release makes the health check fire earlier in the request lifecycle than security, locale, and routing logic — meaning fewer false "unhealthy" alarms and faster, more trustworthy incident detection. There is no new licensing cost and the dependency footprint gets smaller (the Symfony Routing dependency and the bundle's route layer are removed).

To engineering: v1.1.0 is a breaking setup change, and it should be treated as such in the upgrade plan. Remove the previous bundle route imports, register the bundle, and optionally set HEALTHCHECK_PATH. Route-name-based URL generation is gone — grep for health-route name usage. The path is read from the first present environment source at container compile time with a documented default and literal-path normalization, so rebuild the container cache after changing it. Health requests are now handled on kernel.request at PHP_INT_MAX, ahead of routing, security, channel, and locale listeners; the controller stays private internal wiring. Tagged boolean checks, failure logging, and custom HTTP exceptions are preserved. Verification reported: 26 tests / 415 assertions locally, plus all six PHP/Symfony CI combinations green for this commit. Scope expectation-setting: this is the same commit as v1.0.1, reissued under a minor version — do not expect new capabilities, and budget the work as a config/cleanup migration rather than a feature adoption.