Signatur
Beschreibung
win32_set_service_status() teilt dem Windows Service Control Manager (SCM) den aktuellen Status eines als Windows-Dienst laufenden PHP-Skripts mit. Die Funktion ist Teil der win32service-PECL-Extension und wird ausschließlich unter Windows eingesetzt.
Typische Statuswerte sind WIN32_SERVICE_RUNNING, WIN32_SERVICE_STOP_PENDING oder WIN32_SERVICE_STOPPED. Ohne regelmäßige Statusmeldungen kann der SCM davon ausgehen, dass der Dienst nicht mehr reagiert, und ihn beenden oder als fehlerhaft markieren.
Der optionale Parameter $checkpoint wird beim Status WIN32_SERVICE_START_PENDING, WIN32_SERVICE_STOP_PENDING usw. verwendet, um dem SCM Fortschritt zu signalisieren – er sollte bei jedem Aufruf inkrementiert werden, solange der Dienst noch initialisiert oder beendet wird.
Diese Funktion sollte innerhalb der Hauptschleife des Dienstes regelmäßig aufgerufen werden, um dem SCM zu signalisieren, dass der Dienst noch aktiv und funktionsfähig ist.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $status Pflicht | int | Der neue Dienststatus. Gültige Werte sind Konstanten wie WIN32_SERVICE_RUNNING, WIN32_SERVICE_STOPPED, WIN32_SERVICE_STOP_PENDING, WIN32_SERVICE_START_PENDING usw., die von der win32service-Extension bereitgestellt werden. |
|
| $checkpoint | int | 0 | Ein Fortschrittszähler, der bei langen Start- oder Stopvorgängen inkrementiert werden sollte, um dem SCM zu signalisieren, dass Fortschritt gemacht wird und der Dienst nicht hängt. |
Rückgabewert
Beispiele
Einfache Dienst-Hauptschleife mit Statusmeldungen
<?php
// Dienst-Startphase signalisieren
win32_set_service_status(WIN32_SERVICE_START_PENDING, 1);
// Initialisierung durchführen (z. B. Datenbankverbindung herstellen)
sleep(2);
// Dienst ist jetzt bereit
win32_set_service_status(WIN32_SERVICE_RUNNING);
// Hauptschleife des Dienstes
while (WIN32_SERVICE_CONTROL_STOP !== win32_get_last_control_message()) {
// Arbeit erledigen
doWork();
// SCM mitteilen, dass der Dienst noch läuft
win32_set_service_status(WIN32_SERVICE_RUNNING);
sleep(5);
}
// Dienst beenden
win32_set_service_status(WIN32_SERVICE_STOPPED);
function doWork(): void {
// Beispiel: Log-Eintrag schreiben
file_put_contents('C:\\service.log', date('c') . " Dienst läuft\n", FILE_APPEND);
}Langen Startvorgang mit Checkpoint-Inkrement signalisieren
<?php
$checkpoint = 1;
// Phase 1: Konfiguration laden
win32_set_service_status(WIN32_SERVICE_START_PENDING, $checkpoint++);
loadConfig();
// Phase 2: Datenbankverbindung herstellen
win32_set_service_status(WIN32_SERVICE_START_PENDING, $checkpoint++);
connectDatabase();
// Phase 3: Cache aufwärmen
win32_set_service_status(WIN32_SERVICE_START_PENDING, $checkpoint++);
warmUpCache();
// Dienst ist betriebsbereit
win32_set_service_status(WIN32_SERVICE_RUNNING);
function loadConfig(): void { sleep(1); }
function connectDatabase(): void { sleep(2); }
function warmUpCache(): void { sleep(1); }// Wichtig · Fallstricke
Plattformbeschränkung: Diese Funktion ist ausschließlich unter Windows verfügbar und erfordert die Installation der win32service-PECL-Extension. Auf Unix/Linux-Systemen ist sie nicht vorhanden.
Ab win32service 1.0.0 wurde die API teilweise geändert: Fehler werden nun als Win32ServiceException geworfen statt als Fehlercodes zurückgegeben. Prüfe die installierte Versionsnummer der Extension, um die korrekte Fehlerbehandlung zu implementieren.
Ein fehlender oder zu seltener Aufruf von win32_set_service_status() kann dazu führen, dass der SCM den Dienst als nicht reagierend einstuft und ihn zwangsbeendet. Die Funktion sollte daher innerhalb der Dienstschleife in regelmäßigen, kurzen Abständen aufgerufen werden.