Signatur
Beschreibung
Die Funktion win32_set_service_exit_mode() steuert das Verhalten eines PHP-gesteuerten Windows-Dienstes beim Beenden. Sie gehört zur PECL-Erweiterung win32service und ist ausschließlich unter Windows verfügbar.
Mit dem Parameter $gracefulMode legen Sie fest, ob Windows nach dem Dienst-Exit einen automatischen Neustart oder eine andere Fehlerbehandlungs-Aktion auslösen soll. Bei WIN32_SERVICE_GRACEFUL signalisiert der Dienst einen regulären Abschluss (kein Fehler), sodass Windows keine Wiederherstellungsmaßnahmen einleitet. Bei WIN32_SERVICE_NOT_GRACEFUL wird ein unerwarteter Abbruch signalisiert, was Windows-seitig Fehlerbehandlungsregeln triggern kann (z. B. automatischer Neustart des Dienstes).
Die Funktion sollte im laufenden Dienst-Prozess aufgerufen werden, bevor der eigentliche Exit-Prozess eingeleitet wird. Typischerweise wird sie in Verbindung mit win32_set_service_exit_code() genutzt, um sowohl den Exit-Modus als auch den Exit-Code des Dienstes gezielt zu steuern.
Ab Version 1.0.0 der win32service-Erweiterung wirft die Funktion eine ValueError-Exception bei ungültigem Parameter anstelle einer PHP-Warnung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $gracefulMode | int | WIN32_SERVICE_GRACEFUL | Der gewünschte Exit-Modus. Erlaubte Werte sind WIN32_SERVICE_GRACEFUL (regulärer, ordnungsgemäßer Abschluss) und WIN32_SERVICE_NOT_GRACEFUL (unerwarteter Abbruch, löst ggf. Windows-Fehlerbehandlung aus). |
Rückgabewert
$gracefulMode-Parameter wird ab win32service 1.0.0 eine ValueError-Exception geworfen.Beispiele
Dienst ordnungsgemäß beenden (graceful)
<?php
// Dienst initialisieren
$status = win32_start_service_ctrl_dispatcher('meinDienst');
// Exit-Modus auf "ordnungsgemäß" setzen (kein Fehler signalisieren)
win32_set_service_exit_mode(WIN32_SERVICE_GRACEFUL);
// Hauptschleife des Dienstes
while (WIN32_SERVICE_CONTROL_STOP !== ($ctr = win32_get_last_control_message())) {
// Arbeit erledigen
sleep(1);
}
// Dienst sauber beenden
win32_set_service_status(WIN32_SERVICE_STOPPED);
?>Unerwarteten Abbruch signalisieren (not graceful)
<?php
try {
// Dienst initialisieren
win32_start_service_ctrl_dispatcher('meinDienst');
// Fehlerfall: Kritischer Fehler aufgetreten
$kritischerFehler = true;
if ($kritischerFehler) {
// Nicht-ordnungsgemäßen Exit signalisieren
// Windows kann den Dienst dadurch automatisch neu starten
win32_set_service_exit_mode(WIN32_SERVICE_NOT_GRACEFUL);
win32_set_service_exit_code(1);
win32_set_service_status(WIN32_SERVICE_STOPPED);
exit(1);
}
} catch (ValueError $e) {
echo 'Ungültiger Exit-Modus: ' . $e->getMessage();
}
?>// Wichtig · Fallstricke
Nur unter Windows verfügbar: Diese Funktion ist ausschließlich mit der PECL-Erweiterung win32service unter Windows nutzbar. Auf anderen Betriebssystemen existiert sie nicht.
Versionsunterschiede: Ab win32service-Version 1.0.0 muss die Funktion außerhalb des Dienstkontextes nicht mehr aufgerufen werden — bei falschem Aufruf außerhalb eines Dienst-Prozesses wird eine Win32ServiceException ausgelöst.
Zusammenspiel mit Windows-Fehlerbehandlung: Der Modus WIN32_SERVICE_NOT_GRACEFUL sollte nur bei echten Fehlerszenarien genutzt werden, da er Windows-seitige Fehlerbehandlungsregeln (z. B. automatischer Neustart, Benachrichtigungen) auslösen kann. Ein versehentlicher Einsatz kann zu unerwünschten Neustartschleifen führen.