Signatur
Beschreibung
Win32ServiceException ist die zentrale Fehlerbehandlungsklasse der Win32Service-PECL-Erweiterung. Anstatt wie früher einen Integer-Rückgabewert mit Windows-Fehlerkonstanten (z. B. WIN32_ERROR_FILE_NOT_FOUND) manuell zu vergleichen, werden Fehler nun direkt als Exception geworfen, die abgefangen und ausgewertet werden können.
Die Klasse erbt von RuntimeException und bringt damit die üblichen Methoden getMessage(), getCode() und getPrevious() mit. Der Code der Exception entspricht dem numerischen Windows-Fehlercode (z. B. 1060 für einen nicht vorhandenen Dienst), und die Nachricht enthält eine menschenlesbare Beschreibung des Fehlers.
Typische Situationen, in denen Win32ServiceException geworfen wird, sind: Starten oder Stoppen eines nicht vorhandenen Dienstes, fehlende Berechtigungen beim Zugriff auf den Service Control Manager (SCM) sowie fehlerhafte Konfigurationsparameter bei der Registrierung eines neuen Dienstes.
Durch den Einsatz von try/catch-Blöcken lässt sich die Fehlerbehandlung deutlich übersichtlicher und robuster gestalten als mit dem alten Rückgabewert-basierten Ansatz.
Beispiele
Dienst starten mit strukturierter Fehlerbehandlung
<?php
// Einen Windows-Dienst starten und Win32ServiceException abfangen
try {
win32_start_service('MeinDienst');
echo "Dienst erfolgreich gestartet.";
} catch (Win32ServiceException $e) {
echo "Fehler beim Starten des Dienstes:" . PHP_EOL;
echo "Code: " . $e->getCode() . PHP_EOL;
echo "Meldung: " . $e->getMessage() . PHP_EOL;
}Dienst registrieren und spezifischen Fehler unterscheiden
<?php
// Einen neuen Windows-Dienst registrieren
$config = [
'service' => 'MeinPHPDienst',
'display' => 'Mein PHP Hintergrunddienst',
'description' => 'Demonstrationsdienst fuer Win32Service',
'path' => 'C:\\php\\php.exe',
'params' => 'C:\\dienste\\worker.php',
];
try {
win32_create_service($config);
echo "Dienst erfolgreich registriert.";
} catch (Win32ServiceException $e) {
// Fehlercode 1073 = Dienst existiert bereits
if ($e->getCode() === 1073) {
echo "Dienst ist bereits registriert, kein erneutes Anlegen noetig.";
} else {
throw $e; // Unbekannten Fehler weiterwerfen
}
}// Wichtig · Fallstricke
Berechtigungen: Die meisten Win32Service-Operationen erfordern erhöhte Berechtigungen (Administrator-Rechte). Fehlt die Berechtigung, wird eine Win32ServiceException mit dem Fehlercode 5 (Access is denied) geworfen. Stelle sicher, dass der PHP-Prozess mit ausreichenden Rechten läuft.
Plattform: Win32ServiceException ist ausschließlich unter Windows verfügbar und erfordert die installierte win32service-PECL-Erweiterung. Auf anderen Betriebssystemen existiert die Klasse nicht.
Migration: Vor Version 1.0.0 der Erweiterung gaben Funktionen wie win32_start_service() einen Integer-Fehlercode zurück, der mit Konstanten verglichen werden musste. Dieser Mechanismus ist seit 1.0.0 zugunsten von Exceptions als veraltet markiert und sollte nicht mehr verwendet werden.