README

Exposes a /health JSON endpoint and a health:check CLI command for NeoPHP projects, running a set of pluggable health checks (database connectivity, disk space).

Structure

health-package/
├── composer.json
├── README.md
├── src/
│   ├── HealthPackage.php
│   ├── Controllers/
│   │   └── HealthController.php
│   ├── Check/
│   │   ├── Interface/
│   │   │   └── HealthCheckInterface.php
│   │   ├── DatabaseHealthCheck.php
│   │   └── DiskSpaceHealthCheck.php
│   └── Commands/
│       └── HealthCheckCommand.php
└── config/
    └── health.config.php

What it provides

Feature	File	Discovered by
`GET /health/` — JSON status endpoint	`src/Controllers/HealthController.php`	`RouterManager`
`health:check --project=X` — CLI report	`src/Commands/HealthCheckCommand.php`	`ConsoleManager`
Database connectivity check	`src/Check/DatabaseHealthCheck.php`	used directly by both entry points
Disk free space check	`src/Check/DiskSpaceHealthCheck.php`	used directly by both entry points
Configurable disk threshold	`config/health.config.php`, copied once to `Config/Packages/Health/`	`PackageModule`

Installation (local development)

Root composer.json of the NeoPHP framework:

{
    "repositories": [
        { "type": "path", "url": "packages/health-package" }
    ]
}

Target project's composer.json:

{
    "require": {
        "neophp/health-package": "@dev"
    }
}

composer update

Or, once published:

php bin/neo package:require neophp/health-package --project=MyProject

Enabling the package

// src/MyProject/Config/app.config.php
return [
    // ...
    'packages' => [
        \Vendor\HealthPackage\HealthPackage::class,
    ],
];

Configuration

config/health.config.php is copied once to Config/Packages/Health/health.config.php in the target project, and can be edited freely afterwards:

return [
    'disk_min_free_percent' => 10,
];

Usage

HTTP endpoint

curl http://localhost:800X/health/

{
    "status": "ok",
    "timestamp": "2026-08-05T12:00:00+00:00",
    "checks": {
        "database": { "status": "ok", "message": null, "duration_ms": 3.21 },
        "disk_space": { "status": "ok", "message": null, "duration_ms": 0.05 }
    }
}

Returns HTTP 200 if every check passes, 503 if any check fails — suitable for uptime monitors (Uptime Kuma, Pingdom, a load balancer health probe, etc.).

CLI

php bin/neo health:check --project=MyProject

Exits with code 0 if every check passes, non-zero otherwise — usable in deployment scripts or CI pipelines as a post-deploy smoke test.

Adding a custom health check

Implement HealthCheckInterface and add an instance to the $checks array in both HealthController::index() and HealthCheckCommand::do():

final class RedisHealthCheck implements HealthCheckInterface
{
    public function getName(): string
    {
        return 'redis';
    }

    public function check(Container $container): array
    {
        $start = microtime(true);

        // ... ping Redis

        return [
            'status' => 'ok',
            'message' => null,
            'duration_ms' => round((microtime(true) - $start) * 1000, 2),
        ];
    }
}

License

MIT

neophp / health-package

Maintainers

Package info

Statistics

Security