cli_set_process_title — Funktion · PHP-Referenz

Signatur

cli_set_process_title(string $title): bool

Beschreibung

cli_set_process_title() erlaubt es, den Namen des laufenden PHP-CLI-Prozesses zu ändern, wie er vom Betriebssystem angezeigt wird – etwa in der Ausgabe von ps aux, top oder htop. Das ist besonders nützlich für lang laufende Daemon-Prozesse, Worker-Skripte oder Cronjobs, um sie leichter identifizieren und überwachen zu können.

Die Funktion steht ausschließlich im CLI-SAPI zur Verfügung. In anderen SAPIs (z. B. FPM, Apache) wird sie nicht unterstützt und gibt false zurück. Auf macOS ist die Funktion aufgrund von Betriebssystem-Einschränkungen ebenfalls nicht verfügbar.

Intern wird unter Linux/Unix die C-Funktion prctl(PR_SET_NAME, ...) oder das direkte Überschreiben von argv[0] genutzt, je nach Plattform. Der Titel ist daher auf die systemseitige Maximallänge begrenzt (unter Linux typischerweise 15 Zeichen für prctl-basierte Titel).

Eine verwandte Funktion ist cli_get_process_title(), mit der der aktuell gesetzte Prozesstitel ausgelesen werden kann.

Parameter

Name	Typ	Default	Beschreibung
$title Pflicht	string		Der neue Prozesstitel, der dem Betriebssystem übergeben wird. Zu lange Titel werden je nach Plattform stumm abgeschnitten.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Prozesstitel erfolgreich gesetzt wurde. Gibt false zurück, wenn die Funktion nicht unterstützt wird (z. B. falscher SAPI oder nicht unterstütztes Betriebssystem) oder ein Fehler aufgetreten ist.

Beispiele

Prozesstitel für einen Worker-Daemon setzen

<?php
// Nur im CLI-Modus sinnvoll
if (PHP_SAPI !== 'cli') {
    exit('Dieses Skript muss über die Kommandozeile ausgeführt werden.');
}

$workerName = 'mail-queue-worker';

if (cli_set_process_title($workerName)) {
    echo "Prozesstitel wurde auf '{$workerName}' gesetzt." . PHP_EOL;
} else {
    echo "Prozesstitel konnte nicht gesetzt werden." . PHP_EOL;
}

// Simulierter Worker-Loop
$i = 1;
while ($i <= 3) {
    cli_set_process_title($workerName . ': Job ' . $i . ' verarbeiten');
    echo "Verarbeite Job {$i}..." . PHP_EOL;
    sleep(1);
    $i++;
}

cli_set_process_title($workerName . ': idle');

Prozesstitel wurde auf 'mail-queue-worker' gesetzt. Verarbeite Job 1... Verarbeite Job 2... Verarbeite Job 3...

Prozesstitel lesen und setzen

<?php
// Aktuellen Titel auslesen (vor dem Setzen)
$alteTitle = cli_get_process_title();
echo "Alter Prozesstitel: " . ($alteTitle ?: '(leer)') . PHP_EOL;

// Neuen Titel setzen
cli_set_process_title('mein-php-daemon');

// Neuen Titel auslesen und bestätigen
$neuerTitel = cli_get_process_title();
echo "Neuer Prozesstitel: {$neuerTitel}" . PHP_EOL;

Alter Prozesstitel: (leer) Neuer Prozesstitel: mein-php-daemon

// Wichtig · Fallstricke

Plattform-Einschränkungen: Auf macOS ist cli_set_process_title() nicht funktionsfähig und gibt false zurück. Auf Linux ist die effektiv sichtbare Länge des Titels je nach Anzeigemethode auf 15 Zeichen (prctl) oder die Länge der ursprünglichen Kommandozeile begrenzt.

Nur CLI: Die Funktion ist ausschließlich im CLI-SAPI verfügbar. Ein Aufruf im Webserver-Kontext schlägt stillschweigend fehl.

Es empfiehlt sich, den Rückgabewert zu prüfen und ggf. im Fehlerfall eine Warnung zu loggen, da die Funktion auf manchen Systemen ohne Fehlermeldung scheitert.

Siehe auch

cli_get_process_title posix_getpid pcntl_fork