Health Laravel Package

Getting Started

1. Install only in a compatible legacy app. The package targets Laravel 5.x/6.x-era applications. Run composer require pragmarx/health and expect dependency resolution to be the first real test; on Laravel 9/10+ this will usually conflict with illuminate/* constraints.
2. Register the provider and facade if auto-discovery is unavailable. Add Pragmarx\Health\HealthServiceProvider::class to config/app.php providers and optionally alias Health to Pragmarx\Health\Facades\Health::class.
3. Publish configuration and assets.

   php artisan vendor:publish --provider="Pragmarx\Health\HealthServiceProvider"
   

   Publish the config first, then the public assets if the dashboard is served from the package’s asset route. Clear config cache afterward: php artisan config:clear.
4. Inspect config/health.php before opening the UI. The important keys are the panel definitions, the checks assigned to each panel, route prefix/middleware, and notification channels. This file is the package’s control surface.
5. Open the dashboard route. Typically /health or the configured prefix. You should see a panel of checks with pass/fail state. Use this as a replacement for a hand-rolled /up endpoint and for quick “is the app healthy?” checks during deploys.
6. First useful use case: create a private panel with database, Redis, disk-space, queue, and application-key checks, put it behind auth middleware, and use it during releases to confirm infrastructure dependencies before and after deploy.

Implementation Patterns

• Split panels by audience and sensitivity. Define an internal panel behind auth/can middleware for operators, and a minimal public panel containing only non-sensitive checks (e.g., app key present, HTTP reachability) for status pages or load balancers. Never expose database names, disk paths, or queue details publicly.
• Configure checks declaratively with parameters. Disk checks should specify the paths that matter (storage, upload volumes), database checks should target the exact connection used in production, and HTTP/ping checks should target internal health endpoints with short timeouts. Keep these values in config, not in custom code.
• Use the JSON/check endpoints for external monitoring. Rather than scraping the HTML dashboard, call a single check or panel endpoint from UptimeRobot, Pingdom, or your load balancer. Parse the structured response and treat non-ok states as failures; verify the HTTP status code behavior in your version, since some checks return 200 with a failure body.
• Schedule checks outside the request cycle. Use the Laravel scheduler to run health checks and notification dispatch on a cadence (e.g., every five minutes), and keep the browser dashboard for on-demand inspection. This avoids paying the latency of DB/Redis/HTTP checks on every admin page load.
• Pair notifications with state/threshold logic. Configure mail/Slack notifications for failures, but ensure the notifier does not re-alert on every scheduled run. If the package version lacks deduplication, wrap dispatch in your own state store (cache key per check) so you alert on transitions, not continuously.
• Write custom checks for app-specific invariants. Implement the package’s check contract/class shape (usually a class with a check()/run() method returning a status and message), place it under app/Health/Checks, and register it in the panel config. Good candidates: pending migrations, failed jobs count, storage writeability, third-party API credentials, certificate expiry.
• Integrate with deploy scripts. Hit the internal health endpoint after php artisan migrate and cache warmup in CI/CD. Fail the deploy if critical checks fail; log the JSON response as an artifact for postmortem debugging.
• Cache expensive checks. For checks that shell out, call external APIs, or scan large disks, cache results for 30–60 seconds and have the dashboard read cached values. This prevents an operator refreshing the page from hammering dependencies.
• Use environment-specific panels. Local can have a permissive panel with queue/Redis disabled; staging can enable all checks; production should include only checks that are meaningful and reliably passing when the system is healthy. Avoid checks that depend on developer machines.

Gotchas and Tips

• The package is effectively unmaintained. Last release was 2019, and it is not a good fit for modern Laravel. Before adopting, check Composer constraints against your framework version. For new projects, prefer actively maintained alternatives such as Spatie’s Laravel Health or a hosted monitor; for legacy systems, pin the package and isolate it behind an internal route.
• Routes may be public by default. Confirm the route prefix and middleware in config. Add auth, IP allow-listing, or a signed URL before exposing the dashboard. This is the most common operational mistake with health dashboards.
• Config caching can mask changes. After editing panels, checks, or notification settings, run php artisan config:clear (and config:cache in deploy). If a check “disappears,” cached config is the first suspect.
• Asset publishing is easy to forget. A blank or unstyled dashboard usually means public assets were not published or the asset URL does not match a subdirectory deployment. Check the package’s asset route and your APP_URL/proxy configuration.
• Slow checks cause false timeouts. HTTP checks to unreachable hosts, DNS lookups, and SSL checks can block for a long time. Set explicit timeouts, run them on a schedule rather than synchronously, and avoid putting them in a public panel that a load balancer polls frequently.
• False negatives are common in local/staging. Queue checks fail without a worker; Redis checks fail if the local service is down; disk checks fail on read-only containers. Disable or parameterize these per environment instead of training the team to ignore red indicators.
• Notification storms are a real risk. If the notifier fires on every check run, a sustained outage produces continuous email/Slack noise. Add transition-based alerting, a cooldown cache key, or route notifications through your own wrapper.
• Proxy and TLS environments need care. SSL certificate checks and “is the app reachable” checks may fail behind load balancers, terminated TLS, or trusted proxies. Verify TrustProxies and test from the same network perspective as production monitoring.
• Check exceptions may appear as generic failures. If a custom check throws, the dashboard may show only a failed state. Log the exception message, run the check individually via its route, and inspect storage/logs/laravel.log; add try/catch inside custom checks to return a useful diagnostic message.
• Treat the dashboard as diagnostic, not authoritative. Use it alongside application logs, queue metrics, and APM. A green panel means the configured checks passed, not that the application is functionally healthy.
• Extension points are config-driven. Custom checks and notifiers are the main extension surfaces. Keep custom code in your app namespace and avoid editing vendor files; if you must patch the package, fork it and pin your fork in composer.json.