Healthcheck Bundle Laravel Package

Technical Evaluation

Architecture fit. v1.1.0 changes the package's integration surface fundamentally. The health check is no longer a route registered into the application's router; it is a request listener bound to kernel.request at PHP_INT_MAX, which means it short-circuits before routing, security, channel, and locale listeners. For the primary use case — load balancer / k8s / uptime probes — this is a better fit: constant-time, deterministic responses that do not depend on router warm-up, auth middleware chains, session state, or locale negotiation. The trade-off is that the endpoint is deliberately outside the application's middleware stack, so it is unconditionally public and invisible to route-level tooling (route:list, route caching, route-based authorization, API gateway route introspection).

Integration feasibility. This is a breaking change, not a minor feature bump. Three concrete breakages: (1) any require/import of the package's route file must be removed or the app will fail to boot cleanly; (2) named-route URL generation is gone, so any code, view, test, or health-probe config calling route('healthcheck')-style helpers breaks; (3) HEALTHCHECK_PATH is now resolved from the first present environment source at container compilation, so it is baked into the compiled container and will not respond to runtime env changes. Feasibility is otherwise high — the diff is a deletion plus a listener, no new dependencies (the direct Symfony Routing dependency is removed), so the dependency footprint shrinks.

Technical risk.

• Framework-semantics risk (highest). kernel.request at PHP_INT_MAX is Symfony HttpKernel vocabulary. Laravel's HTTP kernel does not dispatch Symfony's kernel.request in the same lifecycle; confirm the package actually binds into Laravel's request pipeline (or requires the Symfony framework bundle) before committing. If the package is Laravel-adjacent rather than Laravel-native, this release may not work at all in a Laravel app.
• Priority tie-break risk. PHP_INT_MAX is a shared ceiling; if any other listener registers at the same priority, ordering falls back to registration order, which is not something the package controls.
• Config-drift risk. Compile-time env resolution means a stale container cache silently serves the old path — a realistic cause of "health check 404 after deploy."
• Silent-bypass risk. Probes now succeed regardless of app health beyond the tagged boolean checks; teams may over-trust a green signal that no longer exercises routing, middleware, or locale code paths.

Key questions.

1. Does the listener register against Laravel's request lifecycle, or does it require the Symfony HttpKernel pipeline? Which Laravel versions are supported?
2. What is the documented migration path for consumers who generate the health URL via named route — static path constant, config value, or env?
3. Where exactly is "the first present environment source" — .env, process env, $_SERVER, or config? What is the precedence order, and is it deterministic across container builds?
4. Is HEALTHCHECK_PATH validated/normalized for leading slash, trailing slash, and path traversal? What happens with an empty or malformed value?
5. Are the tagged boolean checks still evaluated on every probe, and what is their cost (DB/Redis/cache round-trips) at probe frequency?
6. Is the v1.1.0 == v1.0.1 commit identity intentional versioning cleanup, and does that mean anyone already on 1.0.1 takes zero code change?

Integration Approach

Stack fit. Good fit for stateless containerized deployments behind an L7 load balancer or orchestrator probe, where the health endpoint should be cheap and independent of application middleware. Poor fit if the platform requires the health endpoint to traverse auth, tenancy, channel, or locale resolution — those are now explicitly skipped, and there is no supported way to re-enable them.

Migration path (from 1.0.x).

1. Remove the package route file import/require from the route service provider or route files.
2. Grep the codebase, views, test suite, IaC, and probe configs for named-route usage and replace with the literal configured path.
3. Set HEALTHCHECK_PATH in the deploy environment (or accept the documented default).
4. Rebuild the container cache as a mandatory deploy step (config:cache/cache:clear equivalent) — this must be in the pipeline, not left to operators.
5. Verify via curl against a freshly deployed instance, and confirm the response appears in logs without passing through routing.

Compatibility. No new runtime dependencies, and one direct dependency (Symfony Routing) is dropped — a net positive for dependency-conflict risk. Semver-wise this release is labeled minor while containing breaking changes; treat it as major for planning, pinning, and changelog communication. Because v1.1.0 publishes the same commit as v1.0.1, teams already on 1.0.1 need no code change but should still adopt the version for supportability.

Sequencing. Ship behind a feature flag or in a non-production environment first; deploy the path-config and cache-rebuild pipeline changes before the package bump so the deploy is not dependent on a manual step; keep the old route-based endpoint temporarily reachable during cutover so probes never see a gap; retire it only after two clean deploy cycles.

Operational Impact

Maintenance. Lower ongoing surface: no route file, no router coupling, no direct routing dependency. The maintenance cost shifts to the deploy pipeline — the compile-time env read makes container cache invalidation a hard prerequisite for any path change, so that step must be codified, not documented-and-forgotten.

Support. Expect two support clusters at ramp: (a) 404s after deploy caused by stale container caches or a HEALTHCHECK_PATH set in a source the resolver does not read first; (b) broken URL generation in downstream tooling still calling the removed named route. Both are cheap to fix but expensive to diagnose without a clear migration note. Publish the env-source precedence and default path explicitly in the upgrade guide.

Scaling. Strong. The listener runs at maximum priority with no routing, middleware, or session work, so probe cost is roughly constant and independent of application complexity — exactly what you want when probe frequency scales with replica count. The remaining scaling variable is the cost of the tagged boolean checks; if any of those touch the database or a shared cache, high-frequency probing across many replicas becomes a real load source and should be sized or cached deliberately.

Failure modes.

• False green. Probes bypass routing, security, and locale — a passing health check no longer proves the request pipeline works. Pair it with a separate smoke test that hits a real routed endpoint.
• Cache staleness. Env resolved at compile time → old path served until cache rebuild; looks like a routing bug, is actually a build bug.
• Silent 404 vs. hard fail. Removing the route layer means a misconfigured path returns the application's normal 404 (or auth redirect) rather than a package-specific error — ambiguous signal for on-call.
• Listener collision. Another PHP_INT_MAX listener winning the tie-break and preempting the health response.
• Unintended exposure. The endpoint is public by construction; if the path is guessable, it becomes an externally reachable, unauthenticated surface — restrict at the edge.

Ramp-up. Low for a competent Laravel team: one listener, one env var, one controller kept private. Realistic estimate is half a day to a day including the migration sweep for named-route usage and the pipeline change for cache rebuilds, plus a short verification window. The genuine unknown — and the item to resolve before committing — is whether the kernel.request binding actually engages in a Laravel application; that should be a spike, not an assumption.