Statamic Healthchecks Laravel Package

Getting Started

This addon exposes health-check endpoints for a Statamic site so external monitors and load balancers can tell whether the app — not just the PHP process — is healthy. Release 1.1.0 is purely a compatibility widening: it adds Statamic 6 support (PR #1). There are no API, config, or output changes, so upgrading is a non-event for existing installs.

1. Install the right constraint for your Statamic version.

   # Statamic 5 sites
   composer require govigilant/statamic-healthchecks:^1.0
   
   # Statamic 6 sites (only possible from 1.1.0 onward)
   composer require govigilant/statamic-healthchecks:^1.1
   

   Statamic addons are auto-discovered; no manual providers entry should be needed. Run php artisan statamic:addons (or check Tools → Addons in the CP) to confirm it registered.

2. Publish and read the config first. This is the single highest-value five minutes:

   php artisan vendor:publish --tag="statamic-healthchecks-config"
   

   Confirm the exact tag and file path from the package README. The config is where you decide which checks run, whether the endpoint is public, and what the response body looks like.

3. Hit the endpoint locally.

   curl -s -o /dev/null -w '%{http_code}\n' https://my-site.test/health
   curl -s https://my-site.test/health | jq
   

   A healthy site returns 200; a failing check should return 503. Verify both paths — deliberately break something (e.g. make a content directory read-only) and confirm you actually get a 503 with a useful body. A health check that never fails is worse than none.

4. First real use case: wire the URL into your uptime monitor (Better Uptime, UptimeRobot, Pingdom, Oh Dear) with a 60-second interval and alerting on non-200. That single step is usually the entire ROI of the package.

Implementation Patterns

Monitor vs. orchestrator URLs. Keep two consumers in mind:

• Uptime monitors want a lightweight, shallow check — is the app booting, is the Stache readable, is the cache store reachable.
• Load balancers / Kubernetes probes want a fast, no-side-effect check that must never touch the database or filesystem heavily. Health endpoints are polled every few seconds; expensive checks will DDoS your own app.

If the package lets you define multiple endpoints or named check groups, split them into a cheap /health/live (process is up) and a richer /health/ready (dependencies reachable), and point each consumer at the appropriate one.

Deployment smoke test. The most underused pattern — assert health right after deploy and fail the pipeline:

php artisan migrate --force
php artisan statamic:stache:warm   # or your cache warm step

for i in $(seq 1 10); do
  code=$(curl -s -o /dev/null -w '%{http_code}' https://my-site.com/health)
  [ "$code" = "200" ] && break
  sleep 5
done
[ "$code" = "200" ] || { echo "Health check failed: $code"; exit 1; }

This catches the classic Statamic deploy failure — stale Stache or unwritable content//storage/ after a permissions change — before users do.

Post-deploy verification for cache/Stache-sensitive changes. Any release that changes blueprints, collections, or fieldset structure should be followed by a health assertion. It's a cheap guard against a deploy that "succeeded" but left the site throwing 500s on entry rendering.

Environment-specific protection. Health output can leak infrastructure detail (PHP version, extension list, driver names). In production either restrict the route by IP/middleware or ensure the body is generic. In local/staging, keep it verbose — it's a genuinely useful debugging aid.

Statamic 6 upgrade path. If you're planning the Statamic 6 move, this release unblocks you, but sequence it deliberately:

composer require govigilant/statamic-healthchecks:^1.1 --with-all-dependencies
php artisan statamic:stache:clear && php artisan statamic:stache:warm
php artisan test
curl -i https://staging.example.com/health

Treat the health endpoint as your post-upgrade acceptance test rather than the upgrade's conclusion.

Gotchas and Tips

• 1.1.0 is additive. No breaking changes, no deprecations, no config migrations. If you're on 1.0.0 and Statamic 5, staying put is fine; upgrade when convenient. If you're on Statamic 6, ^1.1 is mandatory.
• Composer constraint conflicts. The most likely failure on Statamic 6 is a transitive constraint clash (Statamic 6 pulls newer Laravel/PHP requirements). If composer require fails, read the whole conflict output — it usually names the offending package. Use --with-all-dependencies before resorting to --ignore-platform-reqs, which just defers the breakage.
• Don't let the endpoint be CSRF- or auth-blocked by accident. A health URL that redirects to /login returns 302, which many monitors treat as healthy-but-weird or outright fail. Assert the response body, not just reachability: curl -s .../health | jq -e '.status == "ok"'.
• Route caching. If you deploy with php artisan route:cache, confirm the addon's route survives it. Register-then-cache issues here produce "works locally, 404 in production" — a recurring Statamic addon pitfall.
• Overlap with Laravel's built-in /up route. Laravel 11+ ships a minimal health route. Decide explicitly which one your monitors use; running both without intent leads to alerting on the wrong signal.
• Writable paths matter more than you'd think. On Statamic, health failures are disproportionately filesystem-related (content/, storage/, public/assets/, storage/framework/). When a check goes red after a deploy, check ownership and permissions before suspecting code.
• Extension point: if a check you need is missing, look for the addon's check registry / contract in its src/ directory and register a custom check in a service provider rather than forking. This keeps you upgrade-safe across Statamic majors — which, as 1.1.0 demonstrates, do happen.
• Test the failure mode on staging before trusting it in production. Set a dependency to an unreachable state and confirm the endpoint returns 503 with an actionable message. Verify your monitor actually pages you.