Open source
Alerts for Laravel
composer require roundly-consulting/alerts-for-laravelOverview
Self-hosted health monitoring and alerting that lives inside your Laravel app. Define checks — built-in database, cache, queue, storage and HTTP checks, your own classes or inline closures — and attach them to any notifiable model on a cron schedule. The package opens an alert when a check fails, notifies the right people with throttling, escalates while the failure persists and closes the alert once recovery is confirmed, all on your own scheduler, queue and notification channels. MIT-licensed, with no third-party vendors: the cron parser, timeouts and percentile maths are native.
What you get
Built-in and custom checks
Database, cache, queue, storage and HTTP checks out of the box, your own Check classes and inline closures — each returning ok, warning, failed or skipped.
Facade, DI or actions
One Health facade, the injectable HealthManager behind it, or single-purpose actions — plus Health::fake(), a recording fake for your tests.
Per-owner scheduling
Attach checks to any model — a team, a tenant, a project — on a cron schedule; each owner notifies its own people.
Flap control & confirmed recovery
failAfter() and recoverAfter() gate alerts on consecutive results, so one blip never pages anyone.
Escalation & channel routing
Threshold ⇒ group policies with per-level channels; each level fires exactly once, even under overlapping runs.
Maintenance windows
Mute a check, a tag or everything — for a set time or one owner. Runs keep recording while notifications stay quiet.
Status & history
A health report, a JSON endpoint and a CLI summary, plus uptime and p95 latency from every recorded run.
Documentation
Installation
Install via Composer, publish and run the publish-only migrations, and optionally publish the config and translations.
Configuration
Every config key with its default and env variable — models, key type, job, scheduling, endpoint, muting, history and escalation.
Database schema & key types
The four tables, their columns, and how key_type types the owner morph columns for bigint, UUID or ULID models.
The Health facade
The whole Health facade in one place: the check registry, the for($owner) handle, the silences() sub-accessor and the scheduler verbs.
DI and actions
Inject HealthManager, the facade’s root, or call the action classes directly — with the full facade method to action map.
Registering checks
Register check classes or configured instances with the Health facade or config, and inspect the registry by key.
Built-in checks
Database, cache, queue, storage and HTTP ping checks — their options, thresholds, keys and the default notification they ship with.
Writing checks
Extend Check, implement check() and notification(), read the scheduled row’s meta, and return ok, warning, failed or skipped results.
Inline closure checks
Define one-off checks as closures with Health::define(), configure them fluently, and schedule or run them by key.
Owner models
Implement HasNotifiablesForAlerts and use UsesHealthChecks on any model that owns checks and decides who is notified.
Scheduling checks
Attach a check to an owner with Health::for($owner)->monitor() — presets, cron, throttle, thresholds, tags, routing and meta.
Running checks
How the scheduler, Health::runDue() and the queued job run due checks — and how Health::for($owner)->run() runs one synchronously.
Notifications & throttling
Who gets notified and when, the renotification throttle, the bundled notification, channel routing with notifyVia() and custom notifications.
Flap detection & recovery confirmation
Require consecutive failures before an alert opens and consecutive successes before it closes, so flapping services stay quiet.
Escalation policies
Notify wider groups as a failure persists — threshold ⇒ group policies, named groups on the owner, a global default and exactly-once events.
Maintenance windows & muting
Mute a check, a tag or everything during deploys — for a set time or one owner — while runs and counters keep recording.
Status reports & health endpoint
Read the current health report in code, on the CLI or as an opt-in JSON endpoint that returns 200 or 503 and filters by tag.
Run history, uptime & latency
Every run is recorded with its latency — query uptime and p95 latency over any window, and prune old history automatically.
Timeouts & error handling
Bound checks with per-monitor timeouts, rely on exception-safe runs, and know every exception the package can throw.
Events
HealthCheckFailed, HealthCheckRecovered and HealthCheckEscalated — when each fires and what it carries.
Artisan commands
Run a check on demand, list and inspect checks, print status for CI, prune history, and read the about section.
Testing
Swap the manager for Health::fake() to assert runs without side effects, or test the full pipeline with factories and Laravel fakes.
Requirements
PHP 8.4+, Laravel 12 or 13, a running scheduler and queue worker, and two Roundly packages that Composer installs for you.
Show your open-source love
This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.
More ways to support, including cryptoBy donating, you agree to our donation terms.
Want this built into your product?
We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.