PHPackages                             relistix/health-checker - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. relistix/health-checker

ActiveLibrary[Logging & Monitoring](/categories/logging)

relistix/health-checker
=======================

Laravel package that integrates Healthchecks.io to monitor queue and mail-server availability and provides a configurable ping URL builder.

v1.0.2(2mo ago)098↓50%MITPHPPHP ^8.1

Since Apr 30Pushed 2mo agoCompare

[ Source](https://github.com/relistix/health-checker)[ Packagist](https://packagist.org/packages/relistix/health-checker)[ RSS](/packages/relistix-health-checker/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (8)Versions (3)Used By (0)

relistix/health-checker
=======================

[](#relistixhealth-checker)

A Laravel package that integrates [Healthchecks.io](https://healthchecks.io/docs/) 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
------------

[](#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
----------------------

[](#configuration-overview)

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

- `queue_checks.` — one entry per queue you want to monitor.
- `mail_checks.` — 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

[](#required-env-vars-per-feature)

You want to…Set these env vars (for the `default` check)Build any Healthchecks.io ping URL`HEALTHCHECKER_BASE_URL` (defaults to `https://hc-ping.com`) and **either** a UUID **or** a ping-key + slug pair (see below).Use a UUID-style check`HEALTHCHECKER_QUEUE_DEFAULT_UUID` (or `HEALTHCHECKER_MAIL_DEFAULT_UUID`) — the UUID of the check from the Healthchecks.io UI.Use a slug-style check`HEALTHCHECKER_PING_KEY` (your Healthchecks.io project ping key, applied to all slug-based checks) **and** `HEALTHCHECKER_QUEUE_DEFAULT_SLUG` (or `HEALTHCHECKER_MAIL_DEFAULT_SLUG`). The per-check `ping_key` overrides the global one if set.Probe a queueThe ping target above **and** `HEALTHCHECKER_QUEUE_DEFAULT_NAME` (the queue the probe job will be dispatched onto). Optionally `HEALTHCHECKER_QUEUE_DEFAULT_CONNECTION`.Probe a mail server`HEALTHCHECKER_MAIL_DEFAULT_RECIPIENT` (the Healthchecks.io email-ping address for the check, e.g. `@hc-ping.com`). Optionally `HEALTHCHECKER_MAIL_DEFAULT_SUBJECT` and `HEALTHCHECKER_MAIL_DEFAULT_MAILER`.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

[](#master-onoff-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

[](#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
--------

[](#commands)

### `healthchecker:check-queue`

[](#healthcheckercheck-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`

[](#healthcheckercheck-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)

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
------------------------------

[](#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`:

MethodURL form`success()``/``fail()``//fail``start()``//start``log()``//log``exitStatus(int $code)``//`(Slug-style URLs use `//` instead of `/`.)

---

Testing
-------

[](#testing)

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

Tests use [Orchestra Testbench](https://github.com/orchestral/testbench) and Laravel's built-in `Http::fake()`, `Queue::fake()`, and `Mail::fake()`.

---

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance83

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

85d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1782083?v=4)[Ivan Pavlov](/maintainers/iipavlov)[@iipavlov](https://github.com/iipavlov)

---

Top Contributors

[![iipavlov](https://avatars.githubusercontent.com/u/1782083?v=4)](https://github.com/iipavlov "iipavlov (5 commits)")

---

Tags

laravelmonitoringmailqueuehealthcheckshealthchecks.iouptime

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/relistix-health-checker/health.svg)

```
[![Health](https://phpackages.com/badges/relistix-health-checker/health.svg)](https://phpackages.com/packages/relistix-health-checker)
```

###  Alternatives

[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M136](/packages/laravel-pulse)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77922.3M186](/packages/laravel-mcp)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M133](/packages/roots-acorn)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M246](/packages/laravel-ai)[illuminate/auth

The Illuminate Auth package.

10528.2M1.3k](/packages/illuminate-auth)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)