PHPackages                             rasuvaeff/yii3-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. [Utility & Helpers](/categories/utility)
4. /
5. rasuvaeff/yii3-health-check

ActiveLibrary[Utility & Helpers](/categories/utility)

rasuvaeff/yii3-health-check
===========================

Health check endpoints for Yii3 applications

v1.0.2(3w ago)09↓87.5%BSD-3-ClausePHPPHP 8.3 - 8.5CI passing

Since Jun 2Pushed 3w agoCompare

[ Source](https://github.com/rasuvaeff/yii3-health-check)[ Packagist](https://packagist.org/packages/rasuvaeff/yii3-health-check)[ Docs](https://github.com/rasuvaeff/yii3-health-check)[ RSS](/packages/rasuvaeff-yii3-health-check/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (1)Dependencies (25)Versions (4)Used By (0)

rasuvaeff/yii3-health-check
===========================

[](#rasuvaeffyii3-health-check)

[![Stable Version](https://camo.githubusercontent.com/1e2eca8bbbc30f11080c10de1800587158b8317cccd5c492b6eca3bf74e6d8e7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7261737576616566662f796969332d6865616c74682d636865636b2e737667)](https://packagist.org/packages/rasuvaeff/yii3-health-check)[![Total Downloads](https://camo.githubusercontent.com/3fa0b8a414cf02c402896909298c2ce57f6c944a95f53bc1c421ffef43c28077/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7261737576616566662f796969332d6865616c74682d636865636b2e737667)](https://packagist.org/packages/rasuvaeff/yii3-health-check)[![Build](https://camo.githubusercontent.com/0454d4d59d6ec33773f45f2233be12b4178499a9b81b4e80f439a36217bd5b99/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261737576616566662f796969332d6865616c74682d636865636b2f6275696c642e796d6c3f6272616e63683d6d6173746572)](https://github.com/rasuvaeff/yii3-health-check/actions)[![Static Analysis](https://camo.githubusercontent.com/64ce1cdb418932eec010bcb4dd23693647cfd79a71836cfe324562c078f1eb11/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261737576616566662f796969332d6865616c74682d636865636b2f7374617469632d616e616c797369732e796d6c3f6272616e63683d6d6173746572)](https://github.com/rasuvaeff/yii3-health-check/actions)[![Psalm Level](https://camo.githubusercontent.com/c05996788ae434d070def332e4d8bd454fc358273de444e9e0d1dcd318917340/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5073616c6d2d312d626c75652e737667)](https://github.com/rasuvaeff/yii3-health-check/actions)[![PHP](https://camo.githubusercontent.com/54a8531d87182e3ae9bb08a40b3ba2e511deb8d65a5c9f4ec3f2e40c504a2644/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f7261737576616566662f796969332d6865616c74682d636865636b2f706870)](https://packagist.org/packages/rasuvaeff/yii3-health-check)[![License](https://camo.githubusercontent.com/262df6ba8a344c0c1016d17c4082ac06bfcae27e041410950479516495bad077/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7261737576616566662f796969332d6865616c74682d636865636b2e737667)](LICENSE.md)

Health check endpoints for Yii3: `/live`, `/ready`, `/health`. PSR-15 request handlers with composite checks, elapsed time tracking and Kubernetes probe support.

> Using an AI coding assistant? [llms.txt](llms.txt) has a compact API reference ready to paste into context.

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

[](#requirements)

- PHP 8.3+
- `psr/clock` ^1.0
- `psr/http-factory` ^1.0
- `psr/http-message` ^2.0
- `psr/http-server-handler` ^1.0

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

[](#installation)

```
composer require rasuvaeff/yii3-health-check
```

Usage
-----

[](#usage)

### 1. Register routes

[](#1-register-routes)

```
// config/routes.php
use Rasuvaeff\Yii3HealthCheck\HealthEndpoint;
use Rasuvaeff\Yii3HealthCheck\LivenessEndpoint;
use Rasuvaeff\Yii3HealthCheck\ReadinessEndpoint;
use Yiisoft\Router\Route;

return [
    Route::get('/live')->action(LivenessEndpoint::class)->name('health.live'),
    Route::get('/ready')->action(ReadinessEndpoint::class)->name('health.ready'),
    Route::get('/health')->action(HealthEndpoint::class)->name('health.full'),
];
```

### 2. Register your checks in DI

[](#2-register-your-checks-in-di)

The package ships `config/di.php` and `config/params.php` via config-plugin. Extend `HealthChecker` with your own checks:

```
// config/di.php
use App\Infrastructure\Health\DatabaseHealthCheck;
use App\Infrastructure\Health\RedisHealthCheck;
use Rasuvaeff\Yii3HealthCheck\HealthChecker;
use Yiisoft\Definitions\Reference;

return [
    HealthChecker::class => [
        '__construct()' => [
            'checks' => [
                Reference::to(DatabaseHealthCheck::class),
                Reference::to(RedisHealthCheck::class),
            ],
            'warnThresholdMs' => $params['rasuvaeff/yii3-health-check']['warnThresholdMs'],
        ],
    ],
];
```

### 3. Implement your checks

[](#3-implement-your-checks)

```
// src/Infrastructure/Health/DatabaseHealthCheck.php
use Rasuvaeff\Yii3HealthCheck\HealthCheck;
use Rasuvaeff\Yii3HealthCheck\HealthResult;
use Yiisoft\Db\Connection\ConnectionInterface;

final readonly class DatabaseHealthCheck implements HealthCheck
{
    public function __construct(private ConnectionInterface $db) {}

    public function name(): string
    {
        return 'database';
    }

    public function check(): HealthResult
    {
        try {
            $this->db->createCommand('SELECT 1')->queryScalar();
            return HealthResult::pass(name: 'database');
        } catch (\Throwable $e) {
            return HealthResult::fail(name: 'database', message: $e->getMessage());
        }
    }
}
```

For inline checks without a dedicated class use `CallbackHealthCheck`:

```
use Rasuvaeff\Yii3HealthCheck\CallbackHealthCheck;
use Rasuvaeff\Yii3HealthCheck\HealthResult;

new CallbackHealthCheck(
    name: 'disk',
    check: static function (): HealthResult {
        $free = disk_free_space('/');
        if ($free === false) {
            return HealthResult::fail(name: 'disk', message: 'Cannot read disk stats');
        }
        if ($free < 100 * 1024 * 1024) {
            return HealthResult::warn(name: 'disk', message: 'Less than 100MB free',
                data: ['freeBytes' => $free]);
        }
        return HealthResult::pass(name: 'disk');
    },
)
```

Liveness vs Readiness
---------------------

[](#liveness-vs-readiness)

EndpointHandlerChecksk8s probeOn failure`/live``LivenessEndpoint`None (always pass)`livenessProbe`Container restart`/ready``ReadinessEndpoint`All registered checks`readinessProbe`Removed from load balancer`/health``HealthEndpoint`All registered checksMonitoring/dashboard—**Rule:** never put external service checks (DB, Redis) in liveness — a slow DB would restart your container. Put them only in readiness.

API reference
-------------

[](#api-reference)

### `HealthResult`

[](#healthresult)

```
HealthResult::pass(name: 'db')
HealthResult::pass(name: 'db', message: 'Connected')
HealthResult::warn(name: 'db', message: 'Slow', data: ['latencyMs' => 950])
HealthResult::fail(name: 'db', message: 'Connection refused')

$result->name       // string
$result->status     // HealthStatus
$result->message    // string
$result->data       // array
$result->elapsedMs  // float (set by HealthChecker)

$result->withData(['rows' => 42])   // returns new instance
$result->withElapsedMs(12.5)        // returns new instance
$result->toArray()                  // array, omits elapsedMs:0 and data:[], always includes message
```

### `HealthStatus`

[](#healthstatus)

```
HealthStatus::Pass  // 'pass' → HTTP 200
HealthStatus::Warn  // 'warn' → HTTP 200
HealthStatus::Fail  // 'fail' → HTTP 503
```

### `HealthChecker`

[](#healthchecker)

```
$checker = new HealthChecker(
    checks: [$dbCheck, $redisCheck],
    clock: $psrClock,          // optional PSR-20, default microtime()
    warnThresholdMs: 500.0,    // default 1000.0
);

$checker->add($check);                        // add a check at runtime
$checker->has('database');                    // bool
$results = $checker->run();                   // array
$results = $checker->runByName('database');   // array

HealthChecker::aggregateStatus($results);     // HealthStatus
```

Aggregation rules:

ConditionResultAny `fail``fail`Any `warn`, no `fail``warn`All `pass``pass`### `HealthCheck` interface

[](#healthcheck-interface)

```
interface HealthCheck
{
    public function name(): string;   // /^[a-z][a-z0-9_.-]*$/
    public function check(): HealthResult;
}
```

Exception thrown from `check()` is caught and converted to `HealthResult::fail`.

### `LivenessEndpoint`

[](#livenessendpoint)

```
new LivenessEndpoint(
    responseFactory: $factory,
    statusMessage: 'alive',    // optional, default 'alive'
)
```

Always returns HTTP 200. Never depends on external services.

```
{"status":"pass","message":"alive"}
```

### `ReadinessEndpoint` / `HealthEndpoint`

[](#readinessendpoint--healthendpoint)

```
new ReadinessEndpoint(checker: $checker, responseFactory: $factory)
new HealthEndpoint(checker: $checker, responseFactory: $factory)
```

Both run all registered checks and return the same JSON format.

```
{
    "status": "warn",
    "checks": {
        "database": {"name":"database","status":"pass","message":"","elapsedMs":2.1},
        "redis":    {"name":"redis","status":"warn","message":"Check took 1243.0ms (threshold: 1000.0ms)","elapsedMs":1243.0}
    }
}
```

Warn threshold
--------------

[](#warn-threshold)

`warnThresholdMs` (default: 1000ms) automatically upgrades `pass` → `warn` when a check takes too long. Existing `warn` and `fail` statuses are never downgraded:

```
// warnThresholdMs: 500
// database check took 750ms → upgraded to warn automatically
{"name":"database","status":"warn","message":"Check took 750.0ms (threshold: 500.0ms)","elapsedMs":750.0}
```

Configure via `params.php`:

```
'rasuvaeff/yii3-health-check' => [
    'warnThresholdMs' => 500.0,
    'livenessMessage' => 'alive',
],
```

Kubernetes probes
-----------------

[](#kubernetes-probes)

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

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

Security
--------

[](#security)

- Check names validated: `/^[a-z][a-z0-9_.-]*$/`
- Callbacks are developer-controlled, no user input executed
- Liveness never exposes internal service state

Examples
--------

[](#examples)

See [`examples/`](examples/) for runnable scripts and a full Yii3 wiring guide.

Development
-----------

[](#development)

```
make install
make build
make cs-fix
make mutation
```

License
-------

[](#license)

BSD-3-Clause. See [LICENSE.md](LICENSE.md).

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance95

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity53

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

Total

3

Last Release

25d ago

PHP version history (2 changes)v1.0.0PHP ^8.3

v1.0.1PHP 8.3 - 8.5

### Community

Maintainers

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

---

Top Contributors

[![rasuvaeff](https://avatars.githubusercontent.com/u/1352718?v=4)](https://github.com/rasuvaeff "rasuvaeff (20 commits)")

---

Tags

health-checklivenessmiddlewarephppsr-15readinessyii3middlewareyii3health checkreadinessliveness

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/rasuvaeff-yii3-health-check/health.svg)

```
[![Health](https://phpackages.com/badges/rasuvaeff-yii3-health-check/health.svg)](https://phpackages.com/packages/rasuvaeff-yii3-health-check)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.1B4.1k](/packages/guzzlehttp-psr7)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[cakephp/cakephp

The CakePHP framework

8.8k19.5M1.8k](/packages/cakephp-cakephp)[mcp/sdk

Model Context Protocol SDK for Client and Server applications in PHP

1.5k1.5M107](/packages/mcp-sdk)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)

PHPackages © 2026

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