Healthcheck Laravel Package

Getting Started

1. Install it:

   composer require zanichelli/healthcheck
   

   Laravel auto-discovery should register the service provider — confirm with php artisan about or composer show zanichelli/healthcheck.

   Framework compatibility: as of v1.1.7 the package supports Laravel 13 (added in PR #19). If you're on an older Laravel (10/11/12), earlier 1.1.x tags are fine — but pin the version you tested rather than floating. Check the illuminate/* constraint in composer.json after install; Composer will silently resolve to an older package tag if your framework is too new/old, so verify the installed version matches what you think you're getting.

2. Publish and read the config first:

   php artisan vendor:publish --tag=healthcheck-config
   

   Check the actual tag in the README; the config file is the fastest way to see which checks ship with the package, what the route path is, and what auth mechanism ("security target") it expects.

3. Set the security value in .env (token/key, per the README) — this package's whole purpose is a secured health endpoint, so don't leave it blank or anonymous.

4. Confirm the route is registered:

   php artisan route:list | grep -i health
   

5. First use case — hit it locally and inspect the JSON body:

   curl -i -H "X-Health-Token: $HEALTHCHECK_TOKEN" http://localhost:8000/health
   

   You want a 200 with a per-check breakdown. That body is what you'll wire into CI, k8s probes, and uptime monitors later.

Where to look first: config/healthcheck.php → the route definition → the built-in check classes in src/. The README + those three files are the whole surface area.

Implementation Patterns

K8s / Docker / LB probe Point liveness and readiness at the route. Keep liveness shallow (app boots, container alive) and readiness deep (DB, cache reachable) — if the package only exposes one route, use separate check sets per environment or a ?checks= query if supported.

CI/CD post-deploy smoke test

curl -fsS -H "X-Health-Token: $TOKEN" "$APP_URL/health" | grep -q '"status":"ok"'

Fail the pipeline on non-2xx or on any component reporting failed. This catches migration/config drift that unit tests miss.

Secured target pattern Combine the package's own token with standard Laravel middleware: throttle:60,1, IP allowlist, or restrict the route to the internal network via your ingress. Never expose the raw endpoint to the public internet — a health endpoint is an information leak (versions, service names, DB latency).

Custom checks For app-specific concerns — queue backlog, writable storage/, Stripe/S3 reachability, pending migrations — implement the package's check contract (or extend its base check class). Keep each check:

• Fast (< 1s; the endpoint is polled every few seconds).
• Side-effect free (no writes, no migrations, no cache warmups).
• Exception-safe — catch inside the check and report failed with a reason instead of letting a 500 bubble up.

Environment-aware composition Only run Redis/S3/external-API checks in environments where those services are actually configured. Wrap in config flags so local dev and CI don't report false failures. This matters more now that the package tracks Laravel releases — a matrix of app versions (12 → 13) against one health config will surface checks that only make sense on some versions.

Monitoring integration Point UptimeRobot / BetterStack / Pingdom at the endpoint and parse the JSON body for a status page. Because the body is per-check, you get component-level status for free instead of a single binary up/down.

Debug/admin route If you need heavier diagnostics (config dump, version info, disk usage), put them behind auth + admin gate on a separate route — don't bloat the polled health endpoint.

Gotchas and Tips

• Tiny package, low bus factor. 4 stars, few dependents, one active contributor per release. Pin the exact version in composer.json and read the source before upgrading. Treat the README as the contract and the src/ as the tiebreaker.
• Laravel 13 support landed in v1.1.7 (single PR, no other changes). It's a compatibility bump, not a rewrite — but it means the illuminate/support constraint moved. If you're upgrading your app to Laravel 13, upgrade the package in the same deploy and re-run your smoke test; a resolved older package tag against a new framework is a silent source of boot failures. Conversely, nothing in 1.1.7 should break a Laravel 10–12 install.
• "Security target" is literal. The endpoint is reconnaissance bait. Gate it with token + network policy before it ever leaves localhost. A leaked health endpoint reveals DB names, service topology, and failure modes.
• Config/route caching. After publishing config or changing the token, run php artisan config:clear route:clear locally and confirm your deploy pipeline rebuilds caches — stale caches silently mask config changes.
• False negatives from slow dependencies. A slow DB can render the whole endpoint down, tripping your orchestrator into a restart loop. Set short connection/query timeouts on checks and distinguish degraded from failed if the package supports multiple statuses.
• Throwing custom checks. One uncaught exception in a custom check can 500 the entire response, making every other check invisible. Always try/catch inside the check.
• Ordering matters. Run cheap checks first (app boot, config) and expensive ones last (external APIs). Frequent polling multiplies cost.
• Caching traps. If health results are cached, a stale ok hides an outage. Short TTL, or bypass cache for readiness checks.
• Testing. In phpunit.xml set the token env var and disable external checks via env overrides; then $this->get('/health') with the header in feature tests. If you support multiple Laravel versions, run these tests across the matrix — the package's own CI breadth is not a guarantee for your app's wiring.
• Debugging. The response body tells you what failed but rarely why. Log check duration and exception messages (redacted) alongside the status so you can correlate a red health check with application logs.
• Extension points to remember: the config file (checks, route path, middleware), the check contract (custom checks), and the middleware list (auth/throttle). Those three cover almost every customization you'll need.