thoemo

Repositories Projects Packages

8

thoemo/app-health (1.0.8)

Published 2026-10-25 14:30:42 +00:00 by elnebuloso

Installation

Setup this registry in your ~/.composer/config.json file:

{
	"repositories": [{
			"type": "composer",
			"url": ""
		}
	]
}

Or add the registry to your project's composer.json from the command line:

composer config repositories.thoemo composer 

To install the package using Composer, run the following command:

composer require thoemo/app-health:1.0.8

For more information on the Composer registry, see the documentation.

About this package

Application Health Handling

thoemo/app-health

Runs a list of health checks ("probes") in order and records a status and message on each one. It has no output format of its own: you read the results from the probes and render them however your application needs (JSON endpoint, CLI, ...).

Requirements

• PHP >= 8.2
• No other dependencies

Installation

The package is served by the Forgejo Composer registry (no credentials needed). Add the repository to your composer.json:

"repositories": {
    "packages.link.thoemo.net/thoemo": {
        "type": "composer",
        "url": "https://packages.link.thoemo.net/api/packages/thoemo/composer"
    }
}

Then:

composer require thoemo/app-health

The namespace is elnebuloso\AppHealth.

Overview

Class	Purpose
Probe	One health check. Extend it and override check(). Holds name, status, message and flags.
ProbeResult	Value returned by Probe::check(): a status and an optional message.
Actuator	Collects probes with addProbe() and runs them with check().

Statuses are plain strings, available as constants on Probe:

Constant	Value
Probe::STATUS_SKIPPED	"skipped"
Probe::STATUS_SUCCESS	"success"
Probe::STATUS_WARNING	"warning"
Probe::STATUS_ERROR	"error"

Probe defaults: name "Probe", status skipped, message null, status on exception error, break on error true. The base Probe::check() always returns success.

Usage

Define a probe by extending Probe:

use elnebuloso\AppHealth\Probe;
use elnebuloso\AppHealth\ProbeResult;

final class DatabaseProbe extends Probe
{
    public function __construct(private PDO $pdo)
    {
        $this->setName("database");
    }

    public function check(): ProbeResult
    {
        $this->pdo->query("SELECT 1");

        return new ProbeResult(Probe::STATUS_SUCCESS);
    }
}

final class DiskSpaceProbe extends Probe
{
    public function check(): ProbeResult
    {
        if (disk_free_space("/") < 1_000_000_000) {
            return new ProbeResult(Probe::STATUS_WARNING, "less than 1 GB free");
        }

        return new ProbeResult(Probe::STATUS_SUCCESS);
    }
}

Register the probes and run them:

use elnebuloso\AppHealth\Actuator;
use elnebuloso\AppHealth\Probe;

$diskSpace = new DiskSpaceProbe();
$diskSpace->setName("disk");
$diskSpace->setStatusOnException(Probe::STATUS_WARNING);

$actuator = new Actuator();
$actuator->addProbe(new DatabaseProbe($pdo));
$actuator->addProbe($diskSpace);
$actuator->check();

foreach ($actuator->getProbes() as $probe) {
    printf("%s: %s %s\n", $probe->getName(), $probe->getStatus(), $probe->getMessage() ?? "");
}

What Actuator::check() does:

• Runs the probes in the order they were added and copies the status and message of each returned ProbeResult onto the probe.
• If check() throws, the probe gets getStatusOnException() as status (default error) and the exception message as message.
• If a probe ends with status error and breakOnError() is true (the default), the remaining probes are not run and keep their current status (skipped for a fresh probe). Call setBreakOnError(false) on a probe to keep going after it fails. A warning never stops the run.

Development

Tests and tools run in Docker through redo; build.yml holds the project's redo properties.

redo composer:install phpunit                     # tests on PHP 8.2 (php_version in build.yml)
redo composer:install phpunit -Dphp_version=8.4   # tests on another PHP version
redo commit                                       # clean:dist, prettier:fix, phplint, phpunit, composer:validate:require

Releases

Every push to main runs the GitLab pipeline: phplint, composer:validate:require and phpunit on PHP 8.2 to 8.5. It then raises the patch version in VERSION and uploads that version to the Forgejo registry. Only README.md, composer.json and src/ are part of the released archive.

Dependencies

Dependencies

ID	Version
php	>=8.2

Details

Composer

2026-10-25 14:30:42 +00:00

0

proprietary

4 KiB

Assets (1)

thoemo-app-health.1.0.8.zip 4 KiB

Versions (3) View all

1.1.1 2026-10-25

1.0.8 2026-10-25

1.0.7 2026-10-25