Health Check Bundle Laravel Package

Technical Evaluation

Architecture fit. A health-check endpoint is an edge concern: a thin route-plus-registry adapter with no domain coupling, no data ownership, and no service-boundary implications. That is inherently good fit — adopting, wrapping, or replacing it is contained to a single controller and a handful of probe classes. The complication is the artifact itself. The description bills this as a Laravel health-check package, but the package name (-bundle), the symfony/framework-bundle dependency, and the DependencyInjection/ + *Bundle.php layout all indicate a Symfony bundle. Nothing here registers with Laravel's service container, route table, or config publisher. For a TPM this is the single decision-critical finding: the spec sheet and the artifact disagree, and the artifact wins. It downgrades the proposition from "drop-in Laravel dependency" to "reusable probe classes and a reference wire format," which is a materially different (and much smaller) value claim.

Integration feasibility. Economically trivial to trial and trivial to abandon: MIT licensed, small surface area, zero transitive ecosystem gravity. The cost of a failed spike is measured in hours, not sprints, which is exactly the risk profile that justifies saying yes to an evaluation. The counterweight is zero dependents and a single star — there is no production evidence anywhere in the ecosystem. If we adopt, we are the first serious adopter, meaning our integration effort is simultaneously the project's QA effort. That is an acceptable trade for an edge concern if it is timeboxed and wrapped; it is not acceptable if it becomes load-bearing infrastructure by accident.

Technical risk.

Key questions.

• Is the Laravel framing real, or is this a Symfony bundle with a Laravel-shaped description? Which check classes are genuinely framework-agnostic?
• Which PHP/Laravel (or Symfony) versions are declared, and is there CI proving that matrix?
• Can we register custom probes and disable built-in ones without forking?
• Are liveness and readiness separable, and does each check have an independent, enforced timeout?
• What are the defaults for auth, IP restriction, and response verbosity?
• What is the result contract — HTTP status only, or a documented JSON schema our orchestrator can consume?
• Is there a stated support window or security disclosure process? (Expect "no.")
• Is the response body safe to expose to a load balancer, or does it leak topology and versions?

Integration Approach

Stack fit. Our runtime is Laravel; the package is Symfony. Two honest options exist. Option one: consume the check classes as a standalone library, registering them behind a Laravel service provider we write ourselves — viable only if the probes are free of Symfony Kernel/ContainerAware coupling, which the spike must confirm. Option two: treat the package as a reference implementation — read its aggregation semantics, status-code logic, and JSON shape, and reproduce them natively. Given the maturity signals, option two is the presumptive default and option one is the upside case.

Migration path. Do not let the application depend on the package's namespace. Define an internal contract first — a HealthCheck interface plus a HealthController that assembles a status payload from an array of checks — and let any package implementation sit behind that seam. Swapping to a hand-rolled controller, to spatie/laravel-health, or to our own probes with Symfony-derived logic then becomes a one-file change. This collapses most of the adoption risk for roughly a day of engineering and is the single highest-leverage move available here.

Compatibility and build-vs-buy. Benchmark before committing: a native /health route covering database, cache, and disk is 20–50 lines and eliminates an unproven third-party dependency entirely. Adopt the package only if its probe set or aggregation behavior is materially richer than what we would write in an afternoon — and be honest that "we would have to write it anyway" is the likely verdict for the framework integration layer. Whatever the outcome, pin to a commit SHA or exact tag; no floating constraints on an unmaintained package.

Sequencing.

1. Spike (0.5 day, one engineer). Read composer.json and the service provider. Install on a scratch branch, hit each endpoint, record payload shape, latency, and whether the probes are portable to Laravel. Produce a written go/no-go.
2. Contract first (0.5 day). Ship the internal HealthCheck seam and a native fallback endpoint regardless of the spike outcome. This is not wasted work under either decision.
3. Adopt behind the seam (1 day, only if the spike passes). Wire the package's probes as one implementation, restrict the route to internal network or orchestrator traffic, and verify no credentials, hostnames, or dependency versions leak.
4. Wire to infrastructure. Kubernetes livenessProbe/readinessProbe or ALB target-group checks, with distinct liveness and readiness semantics.
5. Record the decision. A short ADR noting that we accepted a single-maintainer, zero-adopter component for a non-critical edge concern, with the fork trigger defined.

Operational Impact

Maintenance. Plan to own the code. The correct posture is "vendored dependency with periodic manual review," not "upstream-maintained dependency with a changelog we track." Budget a recurring line item: a quarterly compatibility check against current PHP/Laravel, and a standing fork-ready stance (MIT permits it). Pin the exact version; never let this float.

Support. No support channel with an SLA, no security disclosure process, best-effort volunteer issue response. Any production incident traced here is resolved by our engineers reading the source — so the source must remain small enough to read. Verify that as an explicit spike criterion, not an assumption.

Scaling. Probe traffic is high-frequency by design (every few seconds × N replicas), so cost is dominated by probe behavior rather than request volume. Two controls: cache expensive checks with a short TTL so fifty pods don't issue fifty database round-trips per interval, and exclude the endpoint from access logs and APM tracing or it will dominate telemetry volume and skew latency dashboards. Avoid readiness checks that fan out to shared downstreams, which amplifies load precisely when the system is already degrading.

Failure modes. The dangerous one is correlated failure: a readiness check asserting shared-dependency health (a common database or cache) marks every replica unhealthy at once, and the orchestrator restarts the entire fleet — converting a dependency blip into a self-inflicted outage. Liveness must assert only process responsiveness; readiness may assert dependency health but needs aggressive timeouts and must fail closed on timeout rather than hang. Secondary modes: an open endpoint disclosing dependency topology and version fingerprints, and unhandled exception paths returning 500s that infrastructure reads as "unhealthy."

Ramp-up. Low. One engineer, roughly half a day to spike and one to two days to productionize behind the seam. The real cost is not learning the package — it is the review overhead of admitting an unproven dependency into the runtime: security sign-off, dependency-tree audit, and an explicit decision record. Framed as a timeboxed, wrapped pilot for a non-critical edge concern, the operational risk is proportionate. Framed as a standard third-party dependency, it is not — and that framing is the TPM's call to make.