README

A Laravel package that integrates Healthchecks.io to monitor:

• queue worker availability — by dispatching a probe job that pings Healthchecks.io when (and only when) a worker processes it,
• mail server availability — by sending a probe email to a Healthchecks.io email-ping address,
• and offers a configurable ping URL builder for use in your own scheduled jobs and commands.

No persistent storage. No UI. Configure it, schedule the commands, watch your Healthchecks.io dashboard.

Compatible with Laravel 10, 11, and 12 on PHP 8.1+.

Installation

composer require relistix/health-checker

The service provider is auto-discovered.

Publish the config:

php artisan vendor:publish --tag=healthchecker-config

Optionally publish the mail probe view (only if you want to customize the body):

php artisan vendor:publish --tag=healthchecker-views

Configuration overview

Open config/healthchecker.php. Two top-level arrays drive the package:

• queue_checks.<name> — one entry per queue you want to monitor.
• mail_checks.<name> — one entry per mail flow you want to monitor.

Each is seeded with a default entry. Add more entries to monitor multiple queues or multiple mail flows; reference them by name from the commands.

Required env vars per feature

Multiple checks: copy the default entry under queue_checks or mail_checks, give it a new key, point it at different env vars.

Master on/off switch

Set HEALTHCHECKER_ENABLED=false (default: true) to short-circuit every part of the package. Both scheduled commands return SUCCESS without dispatching or sending mail, and QueueHealthPingJob::handle() no-ops if a job was already on the queue when the flag flipped. Use this to silence probe traffic in local and dev environments without removing the scheduled commands or unsetting your check UUIDs.

HTTP client tuning

• HEALTHCHECKER_HTTP_TIMEOUT — request timeout in seconds (default 5).
• HEALTHCHECKER_HTTP_RETRIES — extra retries on failure (default 0, i.e. one attempt total).

Commands

healthchecker:check-queue

Dispatches a queue health-probe job onto a configured queue. When a worker picks it up, the job POSTs a small JSON body to the configured Healthchecks.io ping URL. If the worker is down, the ping never arrives and Healthchecks.io alerts on the missed check-in.

php artisan healthchecker:check-queue                          # uses 'default' check
php artisan healthchecker:check-queue emails                   # uses 'emails' check
php artisan healthchecker:check-queue emails --queue=high      # override queue
php artisan healthchecker:check-queue emails --connection=sqs  # override connection

healthchecker:check-mail

Sends a plain-text probe email to the configured recipient.

php artisan healthchecker:check-mail                              # uses 'default' check
php artisan healthchecker:check-mail reports                      # uses 'reports' check
php artisan healthchecker:check-mail reports --to=other@host.com  # override recipient

Both commands are designed to fail gracefully: missing or incomplete configuration is logged extensively (including the check name and exactly what is missing) and returns a non-zero exit code. Pinging never throws — a network failure, a misconfigured URL, or a mail-server outage will be logged but will not break your scheduler.

Scheduling

Scheduling is the host application's responsibility. Add the commands to your scheduler however you normally do:

Laravel 11+ (routes/console.php):

use Illuminate\Support\Facades\Schedule;

Schedule::command('healthchecker:check-queue')->everyFiveMinutes();
Schedule::command('healthchecker:check-mail')->hourly();

// Multiple checks:
Schedule::command('healthchecker:check-queue emails')->everyFiveMinutes();
Schedule::command('healthchecker:check-queue reports --queue=reports')->everyTenMinutes();

Laravel 10 (app/Console/Kernel.php):

protected function schedule(Schedule $schedule): void
{
    $schedule->command('healthchecker:check-queue')->everyFiveMinutes();
    $schedule->command('healthchecker:check-mail')->hourly();
}

Make sure php artisan schedule:run is wired into cron, and that workers are running (php artisan queue:work for the queues you probe).

Using the URL builder directly

For ad-hoc pings from your own code:

use Relistix\HealthChecker\Support\PingUrlBuilderFactory;
use Relistix\HealthChecker\Support\Pinger;

public function runImport(PingUrlBuilderFactory $factory, Pinger $pinger): void
{
    $urls = $factory->forQueueCheck('imports'); // or $factory->forMailCheck('reports')

    $pinger->ping($urls->start());

    try {
        // ... do work ...
        $pinger->ping($urls->success(), ['rows' => $count]);
    } catch (\Throwable $e) {
        $pinger->ping($urls->fail(), ['error' => $e->getMessage()]);
        throw $e;
    }
}

Both factory methods return a Relistix\HealthChecker\Contracts\PingUrlBuilder — typehint against the contract in your own code if you want to fake it in tests.

Available URL variants on PingUrlBuilder:

(Slug-style URLs use <base>/<ping_key>/<slug> instead of <base>/<uuid>.)

Testing

composer test
# or a single test:
./vendor/bin/phpunit --filter PingUrlBuilderTest

Tests use Orchestra Testbench and Laravel's built-in Http::fake(), Queue::fake(), and Mail::fake().

License

MIT — see LICENSE.