Laravel Health Laravel Package

Getting Started

1. Install the package: composer require ervinsvilumsons/laravel-health.
2. Publish the config (typical for this package family): php artisan vendor:publish --tag=health-config — then open config/health.php first. That file is the map: it lists registered checks, the route/endpoint settings, notification channels, and environment scoping.
3. Run the default check suite once: php artisan health:check. This is the fastest way to see what ships out of the box and what fails in your environment (DB, cache, disk, queue, etc.).
4. Hit the HTTP endpoint (usually /health) in the browser or with curl. This is the first use case for most teams: a single URL that an uptime monitor or load balancer can poll.
5. v1.0.4 adds a staging path (PR #11). Look at how the published config and any health:check --env=staging-style option are wired before rolling it out. In practice, staging checks let you validate the same suite against a staging database/queue without polluting production signals.

Start with the README’s “Available checks” section and the config file, not the source. The package is designed to be configured, not extended, for 90% of cases.

Implementation Patterns

Endpoint-first monitoring. Register the package’s route and point your external monitor (UptimeRobot, Better Stack, Pingdom, or an internal cron) at /health. Keep the endpoint unauthenticated for infrastructure probes, or protect it with a signed URL / IP allowlist if it leaks internal details. Return a non-200 status on failure so monitors alert correctly.

Scheduled checks with notifications. Add health:check to app/Console/Kernel.php (or the scheduler in routes/console.php for Laravel 11+) and route failures to Slack/email via the package’s notification config. Pattern: run the full suite every 5–15 minutes, but run expensive checks (disk space, external API probes) less frequently. Use withoutOverlapping() and onOneServer() to avoid duplicate alerts on multi-node deployments.

Service-provider registration for app-specific checks. The daily pattern is to register checks close to the code they validate — e.g., a HealthServiceProvider or the existing AppServiceProvider — using the package’s check classes. Group them by domain (database, cache, queue, storage, third-party APIs) so a failing group points directly at the subsystem.

Environment-scoped suites (v1.0.4). The staging addition is most useful as a pattern: define which checks apply in local, staging, and production. Staging can run aggressive checks (queue depth, external sandbox APIs, migration status) that you would not want firing production alerts. Production should run a lean, stable set. Use the config’s environment keys rather than branching in code.

CI and deploy gates. Run php artisan health:check --fail-on-error (or the equivalent exit-code flag) as a post-deploy smoke test. This catches misconfigured env vars, unreachable Redis, or failed migrations before traffic shifts. It is a cheap alternative to a full integration suite in staging.

Custom checks as first-class code. When you need to verify a business invariant (e.g., “at least one active pricing tier,” “payment webhook processed in the last hour”), implement a custom check class and register it. Keep these checks idempotent, read-only, and fast — they run on a schedule, not in a request path.

Dashboard integration. Many teams expose check results to an internal status page or Grafana by caching the health:check JSON output and scraping it. If the package stores results, read from that store rather than re-running checks on demand.

Gotchas and Tips

• Endpoint exposure is the classic mistake. A public /health that reports DB versions, disk paths, or queue names is an information leak. Gate it in production or return only ok/fail while keeping detailed output internal.
• Timeouts cascade. One slow external check can push the whole suite past your monitor’s timeout, producing false “down” alerts. Set per-check timeouts and keep the endpoint’s total runtime under the monitor’s threshold (often 10–30s).
• Queue checks need a running worker. A queue check will fail in environments where the worker is intentionally stopped (e.g., maintenance windows, certain staging setups). Scope queue checks to environments where a worker is expected, or mark them as non-critical.
• Cache and config caching surprise you. After changing config/health.php, run php artisan config:clear locally and php artisan config:cache in deploy. Stale cached config is the most common reason a new check “doesn’t fire.”
• Staging vs. production parity (v1.0.4). The new staging support is only useful if your staging environment actually mirrors production topology. If staging uses SQLite and a sync queue, staging checks will pass while production fails. Keep the check set aligned and the infrastructure as close as practical.
• Exit codes matter for automation. Verify what health:check returns on failure before wiring it into CI; a zero exit code on a failed check will silently pass your deploy gate.
• Notification noise. Route repeated failures through throttling or a “only notify on state change” pattern. Health checks that alert every 5 minutes during a known outage train the team to ignore alerts.
• Extension points. Prefer the package’s check interface and result classes over ad-hoc shell commands in scheduled tasks. Custom checks registered through the package inherit the endpoint output, notifications, and environment scoping for free — shell scripts do not.
• Upgrade discipline. This is a 1.x package with small, frequent releases (v1.0.3 → v1.0.4 was a single staging PR). Pin the version in composer.json, read the changelog before minor bumps, and run health:check in staging after every upgrade. No breaking changes are indicated in v1.0.4, but the staging addition may alter config defaults — diff your published config against the new stub.