Healthcheck Bundle Laravel Package

Getting Started

This package answers health probes (load balancers, Kubernetes liveness/readiness, uptime monitors) from inside your application without going through your normal routing stack.

1. Install the package with Composer and register the bundle/service provider in your bootstrap. If you are upgrading from 1.0.x, delete any routes/healthcheck.php-style import (or bundle route file import) you added previously — the route layer is gone in 1.1.0.
2. Set the probe path via HEALTHCHECK_PATH (falls back to the documented default when unset). Values are treated as literal paths and normalized, so /health and health behave the same, but don't include a query string.
3. Rebuild the container cache after changing HEALTHCHECK_PATH — it is resolved during container compilation, not per request. In Laravel terms: php artisan optimize:clear (or at minimum config:clear) after changing it, and in Docker/Kubernetes make sure the variable is present at build/boot time rather than only in a .env loaded later.
4. First use case: curl -i https://your-app.test/health → expect 200 for HEAD and GET when all checks pass, and a non-2xx when a check returns false.

Start by reading the package's check interface/tag documentation and its listener registration — those two files tell you everything about how probes flow through your app.

Implementation Patterns

Boolean checks, tagged and cheap. Day-to-day usage is writing small classes/services that implement the package's check contract and return true/false, then registering them with the tag the bundle looks for. Keep them fast and dependency-light: a probe fires on every poll interval, so a check that hits a cold database pool or an external API every 5 seconds will hurt. Typical checks: cache reachable, queue connection alive, storage writable, a critical read query succeeds.

Custom HTTP exceptions for degraded states. Instead of returning a plain false and a generic 500, throw a custom HTTP exception from a check (or from your own wrapper) to map a failing subsystem to 503 with a meaningful body. This preserves the package's failure-logging behaviour while giving your orchestrator something actionable.

Don't build routes for it anymore. Because 1.1.0 handles kernel.request at PHP_INT_MAX, the probe is intercepted before routing, security, channel, and locale listeners run. That's the feature: your health endpoint works when the router, session, auth, or locale stack is broken. So:

• Remove any route('healthcheck') calls — named route-based URL generation is no longer provided. Build URLs with url('/'.ltrim(config('...'), '/')) or a plain config value.
• Don't add auth/middleware to the health path; there is no route to attach it to, and the listener intentionally fires earlier.
• Keep the health path out of your routes/web.php and out of CSRF/session considerations entirely.

Environment-specific paths. Set HEALTHCHECK_PATH per environment (e.g. /health in production behind the LB, /_probe in staging to avoid public scanners). Because it's compile-time, treat it like a build-time configuration value — bake it into the image or pass it as a real environment variable — rather than something you flip at runtime.

Integration fit. In Kubernetes, point both liveness and readiness at the same path and let the checks distinguish (fast checks for liveness, dependency checks for readiness). In Laravel, avoid layering your own Route::get('/health') on top — a duplicate route will never be reached and only confuses future readers.

Gotchas and Tips

• Breaking change: no named route. Anything calling route('healthcheck') (or whatever the old route name was) now throws RouteNotFoundException. Grep for it during the upgrade; replace with a URL built from the configured path.
• Breaking change: remove old bundle route imports. Leftover route-file imports can now cause duplicate/dead routing entries or outright errors. Clean your bootstrap and route files in the same commit.
• Stale container cache is the #1 "it doesn't work" cause. Changing HEALTHCHECK_PATH without rebuilding the container leaves the old path live. If /health 404s after a change, clear cached config/container first, don't debug the listener.
• .env may not exist at compile time. The path is read from "the first present environment source during compilation" — so the precedence order matters. If your value only lives in .env (loaded after container compilation), it may be ignored. Prefer real process environment variables (docker run -e, Kubernetes env, CI secrets) for this one setting.
• No auth by design. The listener runs before security. Never put secrets, connection strings, or version banners in the health response body — it is effectively public.
• GET/HEAD only. Other verbs fall through to normal routing, so a POST /health will behave like any unknown route (404/405). Don't rely on the probe path accepting anything else.
• Keep check bodies exception-safe. An uncaught non-HTTP exception in a check surfaces as a generic 500 and buries the real cause. Catch infrastructure exceptions in the check and either return false or throw the package-supported custom HTTP exception so failure logging records something useful.
• Debugging checklist: confirm the bundle/provider is registered → confirm the listener is present (debug:event-dispatcher / container dump) → confirm the compiled path value → curl -I for HEAD and curl -i for GET → check your app log channel for the package's failure entries. Also verify no legacy Route::get('/health', ...) remains to muddy the picture.
• Extension points: the tagged check contract (add your own checks), custom HTTP exception classes (shape the failure response/status), and the application logger (failure logging already wired). No need to fork the controller — it's private internal wiring in 1.1.0, so don't type-hint against it or override it.
• Version note: 1.1.0 is the same commit as 1.0.1 published as a minor. If you are already on 1.0.1, the only real work is the route-import removal and any route() call sites.