PHPackages                             javidev/laravel-health-check - 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. javidev/laravel-health-check

ActiveLibrary

javidev/laravel-health-check
============================

Artisan command that checks DB, cache, queue and storage, and prints a clean console report.

00PHPCI failing

Since Jul 27Pushed todayCompare

[ Source](https://github.com/javierDev03/laravel-health-check)[ Packagist](https://packagist.org/packages/javidev/laravel-health-check)[ RSS](/packages/javidev-laravel-health-check/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Laravel Health Check
====================

[](#laravel-health-check)

[![Latest Version on Packagist](https://camo.githubusercontent.com/7b609f51577498a08f2d50347d5370291231ba1c15a1072f98b6337e7885b970/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a6176696465762f6c61726176656c2d6865616c74682d636865636b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/javidev/laravel-health-check)[![GitHub Tests Action Status](https://camo.githubusercontent.com/64fec7f39612292699deff2a5e77d2723b3e8a54e8fe83982447ca50dbfb8c54/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a617669657244657630332f6c61726176656c2d6865616c74682d636865636b2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/javierDev03/laravel-health-check/actions?query=workflow%3Arun-tests+branch%3Amain)[![PHPStan](https://camo.githubusercontent.com/79ccd43815a7df7150f9d33e770b3c3dce3cb8ab6dfe9bce0fbd9928de10dbaf/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230362d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://phpstan.org)[![Total Downloads](https://camo.githubusercontent.com/1fbb64c77b7877c2dc8511746c13e83ff8604afcfa801aaf4bbfe86aef38a4e8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a6176696465762f6c61726176656c2d6865616c74682d636865636b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/javidev/laravel-health-check)[![License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

**Know if your Laravel app is actually healthy — in one Artisan command.**

Database down? Redis unreachable? S3 failing writes? Queue stuck?
Stop guessing. Run `app:health` and get a clear, timed report in seconds.

```
php artisan app:health
```

```
  Health Check

+----------+--------+----------------------------------------+--------+
| Service  | Status | Detail                                 | Time   |
+----------+--------+----------------------------------------+--------+
| Database | ✔ OK   | Connection OK (mysql)                  | 4.2 ms |
| Cache    | ✔ OK   | Write/read OK (driver: redis)          | 1.1 ms |
| Queue    | ✔ OK   | Connection 'redis' OK (0 pending jobs) | 2.8 ms |
| Storage  | ✔ OK   | Write/read OK (disk: s3)               | 89 ms  |
+----------+--------+----------------------------------------+--------+

  All good (4/4)

```

> **Requires [PHP 8.1+](https://php.net/releases/)** and **[Laravel 10+](https://laravel.com/docs)**.

---

Why this package?
-----------------

[](#why-this-package)

Production incidents rarely start in your controllers. They start when **MySQL refuses connections**, **Redis dies**, **S3 times out**, or the **queue connection breaks**.

This package gives you a battle-ready way to:

Without this packageWith `laravel-health-check`SSH in and poke each service manuallyOne command, one reportWrite ad-hoc scripts per projectInstall once, reuse everywhereGuess what failed in CI / DockerExit code `1` when something is brokenBuild custom JSON for monitors`--json` out of the boxBuilt for developers who ship Laravel apps and want **zero-friction observability** at the infrastructure layer.

---

Features
--------

[](#features)

- **One command** — `php artisan app:health` checks DB, cache, queue & storage
- **Beautiful console output** — status, detail message, and duration per check
- **JSON mode** — pipe into uptime tools, dashboards, or HTTP endpoints
- **Fail-fast for CI & containers** — `--fail-on-error` exits `1` on any failure
- **Zero extra config** — uses your existing Laravel `database`, `cache`, `queue`, and `filesystems` config
- **Safe by default** — probe keys/files are always cleaned up (`try/finally`)
- **Fluent API** — `DatabaseCheck::new()->connection('mysql')`
- **Programmatic runner** — inject `HealthChecker` anywhere in your app
- **Extensible** — write custom checks in ~15 lines with `AbstractCheck`
- **Production-grade internals** — `final` classes, enums, `hrtime` timing, PHPStan level 6, Pint, CI

---

Table of contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Available checks](#available-checks)
- [Programmatic usage](#programmatic-usage)
- [Custom checks](#custom-checks)
- [Scheduling](#scheduling)
- [CI / Docker / Kubernetes](#ci--docker--kubernetes)
- [Architecture](#architecture)
- [Testing](#testing)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Security](#security-vulnerabilities)
- [Credits](#credits)
- [License](#license)

---

Installation
------------

[](#installation)

Install via Composer:

```
composer require javidev/laravel-health-check
```

Laravel auto-discovers the service provider. **No manual registration required.**

### Publish the config (optional)

[](#publish-the-config-optional)

```
php artisan vendor:publish --tag=health-check-config
```

This publishes `config/health-check.php` so you can enable, disable, or reorder checks.

### Local / path development

[](#local--path-development)

Developing the package locally? Add a path repository to your app's `composer.json`:

```
{
    "repositories": [
        {
            "type": "path",
            "url": "../laravel-health-check"
        }
    ],
    "require": {
        "javidev/laravel-health-check": "*"
    }
}
```

```
composer update javidev/laravel-health-check
```

---

Usage
-----

[](#usage)

### Console report

[](#console-report)

```
php artisan app:health
```

Runs every registered check and prints a table with service name, status, detail, and duration in milliseconds.

### JSON output

[](#json-output)

Perfect for uptime monitors, external dashboards, or your own `/health` endpoint:

```
php artisan app:health --json
```

```
[
    {
        "name": "Database",
        "ok": true,
        "status": "ok",
        "message": "Connection OK (mysql)",
        "duration_ms": 4.21
    },
    {
        "name": "Cache",
        "ok": true,
        "status": "ok",
        "message": "Write/read OK (driver: redis)",
        "duration_ms": 1.08
    }
]
```

### Fail on error

[](#fail-on-error)

Exit with code `1` when any check fails — ideal for CI pipelines, cron jobs, and container healthchecks:

```
php artisan app:health --fail-on-error
```

SituationExit codeAll checks pass`0`One or more fail`1`Without `--fail-on-error`, the command always exits `0` so you can still inspect the report.

---

Configuration
-------------

[](#configuration)

```
// config/health-check.php

return [
    'checks' => [
        \JaviDev\HealthCheck\Checks\DatabaseCheck::class,
        \JaviDev\HealthCheck\Checks\CacheCheck::class,
        \JaviDev\HealthCheck\Checks\QueueCheck::class,
        \JaviDev\HealthCheck\Checks\StorageCheck::class,
    ],
];
```

Remove what you don't need. Add your own checks that extend `AbstractCheck` (or implement `HealthCheck`).

---

Available checks
----------------

[](#available-checks)

CheckWhat it doesFluent options**Database**Opens a connection and runs `select 1``->connection('mysql')`**Cache**Writes, reads, and deletes a probe key`->store('redis')`**Queue**Resolves the connection and reports pending jobs`->connection('redis')`**Storage**Writes, reads, and deletes a probe file`->disk('s3')`All checks respect your existing Laravel configuration (`database.default`, `cache.default`, `queue.default`, `filesystems.default`).

Probe keys and files are **always cleaned up**, even when a check fails mid-way.

---

Programmatic usage
------------------

[](#programmatic-usage)

Use the same engine outside Artisan — controllers, jobs, Octane, whatever you need:

```
use JaviDev\HealthCheck\HealthChecker;
use JaviDev\HealthCheck\Checks\DatabaseCheck;
use JaviDev\HealthCheck\Checks\CacheCheck;

$report = app(HealthChecker::class)->run([
    DatabaseCheck::new()->connection('mysql'),
    CacheCheck::new()->store('redis'),
]);

if (! $report->ok()) {
    logger()->critical('Health check failed', $report->toArray());
    // notify Slack, abort deploy, etc.
}

return response()->json($report->toArray());
```

---

Custom checks
-------------

[](#custom-checks)

Extend `AbstractCheck` — timing and exception handling are handled for you:

```