Download the PHP package errly/laravel-errly without Composer

Laravel Errly

Slack error alerts and heartbeat monitoring for Laravel 12 and 13 on PHP 8.2 through 8.5.

Errly sends a Slack message when your application throws an error that matters, and pings an outside monitor so you hear about it when the scheduler or a queue worker stops. Setup is one line in bootstrap/app.php and a Slack webhook.

• Slack alerts with the request, user, server and stack trace
• Filtering that skips 404s, validation and auth errors, and rate limits the rest
• Heartbeats that alert you when the scheduler or a worker stops, even when nothing throws
• Redaction of passwords, tokens and other sensitive fields
• Free and open source under the MIT license

Error notifications currently go to Slack. Discord, Teams and email support are planned. Heartbeats support Healthchecks.io (hosted or self-hosted), and other monitors can be plugged in.

Requirements

• PHP 8.2+
• Laravel 12+
• A Slack workspace with an incoming webhook
• Optional: a Healthchecks.io account for heartbeats

Quick Start

1. Install

2. Create a Slack webhook

1. Go to Slack API Apps
2. Create new app → "From scratch"
3. Enable "Incoming Webhooks"
4. Add a webhook to the channel you want alerts in
5. Copy the webhook URL

3. Add it to .env

4. Register the exception handler

5. Send a test alert

A test notification should appear in your Slack channel.

What an alert looks like

Each alert includes:

• Request details - URL, method, IP, user agent
• User information - ID, email, name (if authenticated)
• Server information - hostname, environment
• Stack trace - with a configurable length

Errors are given a severity:

• CRITICAL - database errors, fatal errors, parse errors
• HIGH - HTTP 500+ errors
• MEDIUM - general exceptions, runtime errors

Configuration

The defaults work without changes. Everything below can be adjusted in config/errly.php:

The same settings through .env:

Filtering

These are ignored by default:

• 404 errors - page not found
• Validation errors - form validation failures
• Auth errors - login failures
• Rate limiting errors - too many requests

Sensitive data

Errly redacts passwords, strips authorization headers, and sanitizes nested request payloads. Add your own fields to the list:

Performance

• Rate limiting - prevents notification spam
• Filtering - only processes errors that matter
• Low memory use - lightweight error context collection

Manual error reporting

Heartbeat Monitoring

An exception alert cannot tell you that nothing is running. If the scheduler or a queue worker dies, no error is thrown and no Slack message is sent. Heartbeats cover that gap: every minute Errly pings an outside monitor, and the monitor alerts you when the pings stop.

Heartbeats are off until you configure a check, so existing installs are unaffected. They need the scheduler running (schedule:run from cron, or schedule:work).

What gets pinged

A queued heartbeat is tried once and never reported as a failure, so an unreachable monitor does not fill failed_jobs or Slack. While a worker is down, only one heartbeat per queue waits in the queue.

Things to know:

• Maintenance mode - Laravel does not run scheduled tasks while the app is down (php artisan down), so every heartbeat stops and the monitor alerts. Pause the checks in your monitor for long maintenance windows.
• sync queue driver - jobs run straight away inside the scheduler, so a queue heartbeat would only prove the scheduler ran. Point queue heartbeats at a real queue connection.
• Unique lock - the one-waiting-heartbeat limit uses your default cache store. With several servers, that store must be shared (Redis, database, Memcached).
• Monitoring tools - the ping requests bypass Laravel's Http client hooks, so Telescope, Pulse and Nightwatch do not record them or the secret ping URL. The queued heartbeat job is a normal job, so Horizon, Telescope and Nightwatch will show one per queue per minute.
• Keep checks secret - anyone with a ping URL, UUID or ping key can ping your checks and hide an outage. Keep them in .env, not in committed config.

Setup with Healthchecks.io

1. Create one check per heartbeat in Healthchecks.io, with a period of 1 minute and a grace time that suits you (for example 5 minutes).

2. Add them to .env. A check can be a full ping URL, a check UUID, or a slug:

3. Check each one reaches the monitor:

This pings straight from the command, so it proves the checks exist, not that your workers run. Leave a check blank in local and staging to keep it off there.

More queues

ERRLY_HEARTBEAT_QUEUE_DEFAULT covers the connection's default queue. Publish the config and add any other queue your workers listen on:

Heartbeat options

Auto-provisioning: Healthchecks.io gives a check created this way a period of 1 day and a grace time of 1 hour, and the period cannot be set from the ping. Change it to 1 minute in the dashboard, or a dead worker can go unnoticed for about a day.

Other monitors

Heartbeat clients are resolved with Laravel's Manager, so you can add your own from a service provider:

Then set ERRLY_HEARTBEAT_CLIENT=my-monitor.

Monitoring a single scheduled task? Laravel already has ->pingOnSuccess($url) and ->pingOnFailure($url) on scheduled events. Errly's heartbeats are for the scheduler and workers as a whole.

Testing

Troubleshooting

Not receiving Slack notifications?

1. Check your webhook URL

2. Verify configuration

3. Check Laravel logs

4. Test manually

Too many notifications?

Enable rate limiting:

Notifications in development?

Use environment filtering:

Heartbeat check not receiving pings?

Run php artisan errly:heartbeat-test and read the reason next to each FAILED line:

• OK (not found) - the UUID does not match a check in Healthchecks.io
• 404 not found - the slug does not match a check (or turn on auto-provisioning)
• 409 ambiguous slug - two checks in the project share that slug

If the test passes but a queue check still goes down, no worker is listening on that queue, or schedule:run is not running.

On cPanel/CloudLinux, /usr/bin/php in cron can be the CGI build: its output starts with Content-type: text/html, and php -v shows cgi-fcgi. Point cron at the command-line binary instead:

errly:heartbeat-test prints a warning when it runs under a PHP build other than the CLI.

Contributing

Contributions are welcome. See CONTRIBUTING.md for details.

See CHANGELOG.md for recent changes.

License

Laravel Errly is open-sourced software licensed under the MIT license.

Credits

• Jerome Coloma - Creator and maintainer
• Laravel Community - Inspiration and feedback
• Spatie - Package development tools

If Errly helps you, star the repo, share it with #LaravelErrly, or join the discussion in Issues.