Laravel Heartbeat Laravel Package

Getting Started

• Install with composer require exolnet/laravel-heartbeat. As of v1.15.0 the package requires Laravel 12+ (Laravel 11 and Testbench 9 were dropped) — check your composer.json platform constraints before running composer update, otherwise Composer will silently keep you on 1.14.x or fail resolution.
• The service provider is auto-discovered; there is nothing to register in config/app.php or bootstrap/providers.php.
• Publish the config file first (php artisan vendor:publish and pick the heartbeat tag — confirm the exact tag name in the package README for your version). This is where you set the route path, middleware, and any checks the endpoint performs.
• Look at the published config, then at the package's route registration, in that order. The config is the whole public surface area of this package; almost every customization you'll want lives there.
• First use case: hit the endpoint locally (GET /heartbeat, or whatever path the config defines) and confirm you get a JSON payload back. Then point an external uptime monitor (Better Uptime, UptimeRobot, Pingdom, a Cloudflare/Kubernetes health check, an ALB target group) at that URL. That single step is 90% of the package's value — it gives you an application-level signal instead of a bare TCP ping.

Implementation Patterns

• Split liveness from readiness. If your config lets the heartbeat touch the database, cache, or queue, treat that endpoint as readiness. Add a second, dependency-free endpoint (or disable the checks) for liveness so Kubernetes/ECS doesn't restart healthy containers just because the database blipped.
• Return meaningful status codes. Monitors key off HTTP status, not the body. Healthy → 200, degraded → 503. If the package always returns 200, wrap it or extend the check so failures are visible to the monitor.
• Exclude it from the noisy parts of the stack. Heartbeat probes fire every 30–60 seconds forever. Keep the route stateless: no session middleware, no CSRF, no auth (or a shared-secret header if it's publicly reachable). Otherwise you'll grow the sessions table and fill access logs with probe traffic.
• CI/CD smoke test. After each deploy to staging, curl -f https://staging.example.com/heartbeat in your pipeline and fail the build on non-2xx. This catches "deploy succeeded but the app can't boot" far earlier than a user report.
• Per-environment config. Enable it in staging/production, point it at a distinct path (or disable entirely) locally and in testing. In feature tests, assert the route returns the expected status with $this->get('/heartbeat')->assertOk().
• Layer on top of, not instead of, deeper health checks. The heartbeat answers "is the app up and can it talk to its dependencies?" For queue depth, disk space, scheduler last-run times, and cert expiry, pair it with spatie/laravel-health and keep the heartbeat cheap.
• Deployment hooks. Use the endpoint in your load balancer target group health check and your container orchestrator's probes so traffic only routes to instances that are actually ready. That is the workflow that pays for the package.

Gotchas and Tips

• v1.15.0 is a breaking change for Laravel 11 users. The release drops Laravel 11 and Testbench 9 support. If you're still on Laravel 11, pin "exolnet/laravel-heartbeat": "^1.14" in composer.json before your next composer update; otherwise you'll get a resolution failure or an accidental downgrade elsewhere in the dependency graph. Upgrade path is: Laravel 11 → 12 first, then bump the heartbeat package.
• Clear caches after touching the config. php artisan config:clear and php artisan route:clear — a cached config or route table will make it look like your new route path "didn't apply."
• Don't hang expensive work off a probe. Anything called by the heartbeat runs every probe interval, on every replica. A slow query here becomes a self-inflicted load problem that scales with your instance count.
• Watch for proxy interference. Cloudflare, ingress controllers, and WAFs may intercept, rate-limit, or rewrite the probe path or its status code. Verify what the monitor actually receives, not what curl on the box shows.
• Log noise is the most common complaint. Either route probe requests to a separate log channel, sample them, or exclude the path in your logging middleware. Don't let a 30-second probe dominate your log volume and your log bill.
• Timestamps and clock skew. If the response includes a server timestamp, remember it's the container clock, not yours — don't build alerting logic on it without NTP guarantees.
• Extension points. For anything the config doesn't cover, register the route yourself in routes/web.php (or api.php) and use Route::has('heartbeat') to check whether the package already claimed the path. Keep custom logic in your app, not in a vendor/ edit — the next composer update will erase it.