README

Health checks and readiness/liveness probes for CakePHP 5 applications.

Ship your app with the endpoints load balancers, Kubernetes, and uptime monitors expect — plus a CLI probe with a meaningful exit code — driven by a small set of pluggable checks.

GET /health/live — liveness: the process is up. Always 200. Public.
GET /health/ready — readiness: runs the checks; 503 when any is critical, otherwise 200. Public, and only ever exposes status strings.
GET /health — detailed report (messages, data, per-check timings), guarded by a token and/or an IP allow-list.
bin/cake health — same checks from the CLI, exit code 1 on critical.

Requirements

PHP 8.1+
CakePHP 5.0+

Installation

composer require ovenlab/cakephp-health

Load the plugin (or add it to Application::bootstrap()):

bin/cake plugin load Health

// src/Application.php
public function bootstrap(): void
{
    parent::bootstrap();
    $this->addPlugin('Health');
}

Configuration

Copy the example config and adjust it:

cp vendor/ovenlab/cakephp-health/config/health.example.php config/health.php

use Health\Check\CacheCheck;
use Health\Check\DatabaseCheck;
use Health\Check\DiskSpaceCheck;

return [
    'Health' => [
        'checks' => [
            'database' => ['className' => DatabaseCheck::class, 'connection' => 'default'],
            'cache' => ['className' => CacheCheck::class, 'config' => 'default'],
            'disk' => [
                'className' => DiskSpaceCheck::class,
                'path' => TMP,
                'warningThreshold' => 80,  // percent used
                'criticalThreshold' => 95,
            ],
        ],
        'guard' => [
            'token' => env('HEALTH_TOKEN'),
            'allowIp' => [],
        ],
    ],
];

The plugin auto-loads config/health.php during bootstrap.

The detailed endpoint guard

GET /health/live and GET /health/ready are always public and only ever return status strings. GET /health also returns check messages and data, so it is guarded. Access is granted when:

no guard is configured (handy for local dev), or
the client IP is in guard.allowIp, or
the request carries a matching token via the X-Health-Token header or the ?token= query string.

curl -H "X-Health-Token: $HEALTH_TOKEN" https://example.com/health

Built-in checks

Check	Class	Key options
Database	`Health\Check\DatabaseCheck`	`connection`
Cache	`Health\Check\CacheCheck`	`config`
Disk space	`Health\Check\DiskSpaceCheck`	`path`, `warningThreshold`, `criticalThreshold`

Writing a custom check

Implement Health\Check\HealthCheckInterface and return a Result:

namespace App\Health;

use Health\Check\HealthCheckInterface;
use Health\Check\Result;

class QueueDepthCheck implements HealthCheckInterface
{
    public function __construct(private array $options = [])
    {
    }

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

    public function run(): Result
    {
        $depth = /* ... */ 0;
        $max = $this->options['max'] ?? 1000;

        if ($depth >= $max) {
            return Result::critical("Queue backlog is {$depth}", ['depth' => $depth]);
        }

        return Result::ok("Queue backlog is {$depth}", ['depth' => $depth]);
    }
}

Then register it in config/health.php:

'queue' => ['className' => \App\Health\QueueDepthCheck::class, 'max' => 500],

A check should never throw — report failures as Result::critical(). If one does throw, the runner catches it and reports the check as critical, so a single broken check can never take down the whole probe.

Kubernetes example

livenessProbe:
  httpGet: { path: /health/live, port: 80 }
readinessProbe:
  httpGet: { path: /health/ready, port: 80 }

CLI

bin/cake health          # exit 0 on ok/warning, 1 on critical
bin/cake health --strict # exit 1 on warning too

ovenlab / cakephp-health

Maintainers

Package info

Statistics

Security