Health Status

HealthStatusModule renders read-only service checks for application dependencies: database, cache, queue workers, search indexes, external APIs, storage, schedulers, and similar operational signals.

Use it when admins need to understand whether the application is healthy before they continue work. The module reads server-owned PHP configuration and renders resolved statuses. It does not submit forms, write records, start jobs, or let the browser choose which service to probe.

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\Health\HealthStatusCheck;
use AlexKudrya\Adminix\Modules\Health\HealthStatusEnum;
use AlexKudrya\Adminix\Modules\Health\HealthStatusResult;
use AlexKudrya\Adminix\Modules\Module;

AdminixPage::uri('operations')
    ->name('operations')
    ->addModule(
        Module::healthStatus()
            ->name('service-health')
            ->title('Service health')
            ->description('Runtime status for critical dependencies.')
            ->addChecks(
                HealthStatusCheck::make('database', 'Database')
                    ->result(HealthStatusResult::healthy('Connected.', ['latency' => '8ms'])),

                HealthStatusCheck::make('queue', 'Queue')
                    ->handler(static fn () => [
                        'status' => HealthStatusEnum::DEGRADED,
                        'message' => 'Two delayed jobs are waiting for retry.',
                        'meta' => ['delayed' => 2],
                    ])
            )
    );

Result: Adminix renders a status card with one row per check, status badges, messages, and small metadata chips. Rows are display-only.

Rendered example:

Statuses

HealthStatusEnum supports:

healthy;
degraded;
down;
unknown.

Use HealthStatusResult::healthy(), degraded(), down(), or unknown() for explicit results. Each result may include a message and optional scalar metadata.

Checks

Each HealthStatusCheck supports:

name() - required stable key, unique inside the module;
title() - visible label;
description() - secondary explanatory text;
icon() - Bootstrap icon class;
status() and message() - static status without a handler;
result(HealthStatusResult::...) - static status, message, and metadata;
handler() - server-side resolver for dynamic checks;
meta() - optional static metadata.

Handlers may return:

HealthStatusResult;
HealthStatusEnum;
one of the status strings;
boolean (true becomes healthy, false becomes down);
an array with status, message, and meta.

Handler exceptions are caught and rendered as a controlled down status with Health check failed..

For reusable checks, implement HealthStatusHandlerInterface:

use AlexKudrya\Adminix\Modules\Health\HealthStatusCheck;
use AlexKudrya\Adminix\Modules\Health\HealthStatusHandlerInterface;
use AlexKudrya\Adminix\Modules\Health\HealthStatusModule;
use AlexKudrya\Adminix\Modules\Health\HealthStatusResult;

final class QueueHealthCheck implements HealthStatusHandlerInterface
{
    public function handle(HealthStatusCheck $check, HealthStatusModule $module, array $params = []): HealthStatusResult
    {
        return HealthStatusResult::healthy('Queue is accepting jobs.');
    }
}

Then configure it:

HealthStatusCheck::make('queue', 'Queue')->handler(QueueHealthCheck::class);

Layout

Module::healthStatus() returns a blank module.
HealthStatusModule::make($name, $title = null) is a short constructor.
title(), description(), and icon() render the card header.
addCheck() and addChecks() attach checks.
fullWidth() spans the page width. This is the default.
halfWidth() lets the module sit in a half-width column on wide screens.

Doctor

adminix:doctor reports:

a health module without checks;
missing check names;
duplicate check names;
invalid static statuses;
invalid handler classes or objects.

Doctor does not execute handlers, so it does not probe external services during configuration checks.

Security

Health checks must stay server-owned. Do not pass service names, DSNs, URLs, credentials, tenant IDs, or handler classes from browser input.

Keep probes short and side-effect free. If a check needs credentials, queues, network access, or third-party API calls, keep those details inside the consuming application's service layer and return only the safe status message that admins should see.

Last modified: 23 July 2026