PHPackages                             philiprehberger/laravel-healthcheck - 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 &amp; Monitoring](/categories/logging)
4. /
5. philiprehberger/laravel-healthcheck

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

philiprehberger/laravel-healthcheck
===================================

Configurable health check endpoint with built-in checks and Kubernetes probe support

v1.1.4(yesterday)15MITPHPPHP ^8.2CI passing

Since Mar 9Pushed todayCompare

[ Source](https://github.com/philiprehberger/laravel-healthcheck)[ Packagist](https://packagist.org/packages/philiprehberger/laravel-healthcheck)[ Docs](https://github.com/philiprehberger/laravel-healthcheck)[ RSS](/packages/philiprehberger-laravel-healthcheck/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (9)Versions (7)Used By (0)

Laravel Healthcheck
===================

[](#laravel-healthcheck)

[![Tests](https://github.com/philiprehberger/laravel-healthcheck/actions/workflows/tests.yml/badge.svg)](https://github.com/philiprehberger/laravel-healthcheck/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/0f49c1a3f4bd09f7800a3f91305c8c5e38f77c5738b6dee620575d24b4de25ba/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068696c69707265686265726765722f6c61726176656c2d6865616c7468636865636b2e737667)](https://packagist.org/packages/philiprehberger/laravel-healthcheck)[![License](https://camo.githubusercontent.com/139670633ec914ecf6243891dcc06a230da279e92b04d9acd2986125bc17d348/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f7068696c69707265686265726765722f6c61726176656c2d6865616c7468636865636b)](LICENSE)

Configurable health check endpoint with built-in checks and Kubernetes probe support.

### Features

[](#features)

- Drop-in health check endpoint at `/health` (configurable prefix)
- Kubernetes liveness (`/health/live`) and readiness (`/health/ready`) probes
- Built-in checks: database, cache, storage, Redis, queue, environment, HTTP
- Pluggable: implement `HealthCheck` to add your own checks
- Per-check timeout with graceful critical fallback
- Optional result caching to reduce backend load
- Configurable middleware and route prefix
- Full test suite, PHPStan level 8, Laravel Pint enforced

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11 or 12

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

[](#installation)

```
composer require philiprehberger/laravel-healthcheck
```

Laravel's package auto-discovery registers the service provider automatically.

### Publishing the config

[](#publishing-the-config)

```
php artisan vendor:publish --tag=healthcheck-config
```

This creates `config/healthcheck.php`.

Usage
-----

[](#usage)

### Basic health check

[](#basic-health-check)

Once installed, the following endpoints are immediately available:

EndpointDescription`GET /health`Full report — `200` if healthy, `503` if not`GET /health/live`Liveness probe — always `200``GET /health/ready`Readiness probe — `200` if healthy, `503` if notExample response from `GET /health`:

```
{
  "status": "ok",
  "duration_ms": 14.52,
  "checks": [
    {
      "name": "database",
      "status": "ok",
      "message": "Database connection is healthy.",
      "meta": { "connection": "mysql" }
    },
    {
      "name": "cache",
      "status": "ok",
      "message": "Cache is healthy.",
      "meta": []
    },
    {
      "name": "environment",
      "status": "ok",
      "message": "Environment configuration looks healthy.",
      "meta": { "env": "production", "debug": false }
    }
  ]
}
```

When any check is **critical** or **warning**, the overall `status` reflects that and the HTTP status code becomes `503`.

### Status levels

[](#status-levels)

LevelMeaning`ok`Check passed`warning`Non-fatal issue (e.g. debug enabled)`critical`Check failed — affects readinessThe overall report status is `critical` if any check is critical; `warning` if any is warning and none is critical; `ok` only if all checks are ok.

### Configuration

[](#configuration)

`config/healthcheck.php`:

```
return [
    'route_prefix' => env('HEALTHCHECK_ROUTE_PREFIX', 'health'),

    'middleware' => [],

    'checks' => [
        \PhilipRehberger\Healthcheck\Checks\DatabaseCheck::class,
        \PhilipRehberger\Healthcheck\Checks\CacheCheck::class,
        \PhilipRehberger\Healthcheck\Checks\StorageCheck::class,
        \PhilipRehberger\Healthcheck\Checks\EnvironmentCheck::class,
    ],

    'timeout' => (int) env('HEALTHCHECK_TIMEOUT', 5),

    'cache' => [
        'enabled' => (bool) env('HEALTHCHECK_CACHE_ENABLED', false),
        'ttl'     => (int) env('HEALTHCHECK_CACHE_TTL', 30),
    ],
];
```

#### Restricting access with middleware

[](#restricting-access-with-middleware)

```
'middleware' => ['auth:sanctum'],
```

Or use a custom IP-allowlist middleware for infrastructure-only access.

#### Enabling result caching

[](#enabling-result-caching)

To avoid hammering your database on every probe poll:

```
HEALTHCHECK_CACHE_ENABLED=true
HEALTHCHECK_CACHE_TTL=30
```

### Built-in checks

[](#built-in-checks)

#### DatabaseCheck

[](#databasecheck)

Tests that a PDO connection can be established.

```
new DatabaseCheck()                    // uses default connection
new DatabaseCheck('mysql_reporting')   // named connection
```

#### CacheCheck

[](#cachecheck)

Writes, reads, and deletes a probe key using the default cache driver. Resource cleanup is guaranteed — the probe key is always removed via `try-finally`, even if cache operations fail.

#### StorageCheck

[](#storagecheck)

Writes, reads, and deletes a probe file on the default filesystem disk. Resource cleanup is guaranteed — the probe file is always deleted via `try-finally`, even if read or content verification fails.

```
new StorageCheck()        // default disk
new StorageCheck('s3')    // named disk
```

#### RedisCheck

[](#redischeck)

Calls `PING` on the Redis connection. Returns a warning (not critical) if the Redis extension and Predis are both absent so the check degrades gracefully in environments without Redis.

```
new RedisCheck()             // default connection
new RedisCheck('cache')      // named connection
```

#### QueueCheck

[](#queuecheck)

Resolves the queue connection from the container to verify connectivity.

```
new QueueCheck()             // default connection
new QueueCheck('redis')      // named connection
```

#### EnvironmentCheck

[](#environmentcheck)

Returns a **warning** when `APP_DEBUG=true` in a production environment.

#### HttpCheck

[](#httpcheck)

Pings an external URL and verifies the response status code.

```
new HttpCheck('https://api.stripe.com')
new HttpCheck('https://api.stripe.com', timeout: 3, expectedStatus: 200, checkName: 'stripe')
```

Register via the service container for constructor-injected checks:

```
// AppServiceProvider::register()
$this->app->bind(\PhilipRehberger\Healthcheck\Checks\HttpCheck::class, fn () =>
    new \PhilipRehberger\Healthcheck\Checks\HttpCheck(
        url: 'https://api.stripe.com',
        checkName: 'stripe_api',
    )
);
```

Then add the class string to `config/healthcheck.php` `checks` array.

### Writing custom checks

[](#writing-custom-checks)

Implement the `HealthCheck` contract:

```
use PhilipRehberger\Healthcheck\CheckResult;
use PhilipRehberger\Healthcheck\Contracts\HealthCheck;

class ElasticsearchCheck implements HealthCheck
{
    public function name(): string
    {
        return 'elasticsearch';
    }

    public function check(): CheckResult
    {
        try {
            $info = app('elasticsearch')->info();

            return CheckResult::ok(
                $this->name(),
                'Elasticsearch is healthy.',
                ['version' => $info['version']['number']],
            );
        } catch (\Throwable $e) {
            return CheckResult::critical($this->name(), $e->getMessage());
        }
    }
}
```

Register in `config/healthcheck.php`:

```
'checks' => [
    // ...
    ElasticsearchCheck::class,
],
```

### Kubernetes probe configuration

[](#kubernetes-probe-configuration)

#### Deployment manifest

[](#deployment-manifest)

```
livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 2
```

**Liveness** (`/health/live`) — always returns `200` as long as PHP-FPM/Octane is alive. Kubernetes will restart the container only if this stops responding, not on application-level failures.

**Readiness** (`/health/ready`) — returns `200` only when all health checks pass. Kubernetes removes the pod from load balancer rotation while this returns `503`, enabling zero-downtime deploys during database migrations or cold-start delays.

#### Ingress — skip auth middleware on probe endpoints

[](#ingress--skip-auth-middleware-on-probe-endpoints)

If you add auth middleware globally, exclude the probe paths in your ingress or use a separate middleware group:

```
// config/healthcheck.php
'route_prefix' => 'health',
'middleware'   => [],   // no auth on probes — protect at the network level instead
```

API
---

[](#api)

### `HealthCheck` (Interface)

[](#healthcheck-interface)

MethodReturn TypeDescription`name(): string``string`Unique check identifier`check(): CheckResult``CheckResult`Execute the check and return a result### `CheckResult`

[](#checkresult)

MethodDescription`CheckResult::ok(string $name, string $message, array $meta)`Passing result`CheckResult::warning(string $name, string $message, array $meta)`Non-fatal warning`CheckResult::critical(string $name, string $message, array $meta)`Failing resultDevelopment
-----------

[](#development)

```
composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse
```

License
-------

[](#license)

MIT

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance100

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

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 ~2 days

Total

6

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfd7d24cbbf32400fa13ce0bbe7a31edd2d66a6d4488eafdb3d64c5337bf0435?d=identicon)[philiprehberger](/maintainers/philiprehberger)

---

Top Contributors

[![philiprehberger](https://avatars.githubusercontent.com/u/8218077?v=4)](https://github.com/philiprehberger "philiprehberger (16 commits)")

---

Tags

laravelmonitoringhealthhealthcheckkubernetesk8s

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/philiprehberger-laravel-healthcheck/health.svg)

```
[![Health](https://phpackages.com/badges/philiprehberger-laravel-healthcheck/health.svg)](https://phpackages.com/packages/philiprehberger-laravel-healthcheck)
```

###  Alternatives

[scoutapp/scout-apm-laravel

Scout Application Performance Monitoring Agent - https://scoutapm.com

23825.7k](/packages/scoutapp-scout-apm-laravel)

PHPackages © 2026

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