fpm_get_status — Funktion · PHP-Referenz

Signatur

fpm_get_status(): array|false

Beschreibung

fpm_get_status() liefert Laufzeit-Statusinformationen über den aktuellen PHP-FPM-Pool direkt aus einem PHP-Skript heraus, ohne einen separaten HTTP-Request an den FPM-Statusendpunkt zu benötigen. Die Funktion gibt ein assoziatives Array zurück, das dieselben Daten enthält, die auch über den konfigurierten pm.status_path in der php-fpm.conf abgerufen werden können.

Typische Felder im Rückgabe-Array umfassen u. a. pool (Name des Pools), process-manager (z. B. dynamic, static oder ondemand), accepted-conn (Anzahl angenommener Verbindungen), active-processes sowie idle-processes. Damit lässt sich der Pool-Zustand programmatisch auswerten, ohne externe Monitoring-Anfragen einzusetzen.

Die Funktion ist besonders nützlich für selbst geschriebene Health-Check-Endpunkte, interne Dashboards oder Logging-Mechanismen, die den FPM-Status direkt aus dem laufenden Prozess auslesen sollen. Sie ist nur verfügbar, wenn PHP als PHP-FPM (FastCGI Process Manager) ausgeführt wird; in anderen SAPIs (CLI, Apache-Modul etc.) gibt sie false zurück.

Da die Funktion intern auf die FPM-Prozessstruktur zugreift, sind keine zusätzlichen Konfigurationsschritte wie das Aktivieren von pm.status_path erforderlich — sie funktioniert unabhängig davon.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein assoziatives Array mit den aktuellen Pool-Statusinformationen zurück. Wird PHP nicht über PHP-FPM ausgeführt oder tritt ein interner Fehler auf, wird false zurückgegeben.

Beispiele

Pool-Status im Health-Check-Endpunkt ausgeben

<?php
// health.php — wird als PHP-FPM-Script aufgerufen
$status = fpm_get_status();

if ($status === false) {
    http_response_code(500);
    echo json_encode(['error' => 'Nicht in einer PHP-FPM-Umgebung']);
    exit;
}

header('Content-Type: application/json');
echo json_encode($status, JSON_PRETTY_PRINT);

{ "pool": "www", "process-manager": "dynamic", "start-time": 1710000000, "start-since": 3600, "accepted-conn": 12345, "listen-queue": 0, "max-listen-queue": 0, "listen-queue-len": 128, "idle-processes": 4, "active-processes": 1, "total-processes": 5, "max-active-processes": 3, "max-children-reached": 0, "slow-requests": 0 }

Status in eine Log-Datei schreiben

<?php
// Periodisch oder bei bestimmten Ereignissen aufgerufen
$status = fpm_get_status();

if ($status !== false) {
    $logEntry = sprintf(
        "[%s] Pool: %s | Aktiv: %d | Leerlauf: %d | Verbindungen: %d\n",
        date('Y-m-d H:i:s'),
        $status['pool'],
        $status['active-processes'],
        $status['idle-processes'],
        $status['accepted-conn']
    );
    file_put_contents('/var/log/fpm-custom.log', $logEntry, FILE_APPEND | LOCK_EX);
    echo "Status protokolliert.\n";
} else {
    echo "Fehler: fpm_get_status() ist nur unter PHP-FPM verfügbar.\n";
}

Status protokolliert.

// Wichtig · Fallstricke

SAPI-Abhängigkeit: fpm_get_status() funktioniert ausschließlich, wenn PHP über PHP-FPM betrieben wird. In der CLI, als Apache-Modul (mod_php) oder unter anderen SAPIs gibt die Funktion false zurück. Prüfe deshalb stets den Rückgabewert.

Verfügbarkeit: Die Funktion wurde mit PHP 8.4.0 eingeführt. Für ältere PHP-Versionen muss der FPM-Status weiterhin über den konfigurierten pm.status_path per HTTP-Request abgerufen werden.

Sicherheit: Gib den Rückgabewert dieser Funktion nicht ungeschützt in öffentlich erreichbaren Endpunkten aus, da er interne Prozessinformationen enthält, die für Angreifer nützlich sein könnten. Sichere solche Endpunkte durch IP-Beschränkungen oder Authentifizierung ab.

Siehe auch

phpinfo php_uname getmypid sys_getloadavg