Signatur
Beschreibung
win32_delete_service() entfernt einen vorhandenen Diensteintrag dauerhaft aus der Windows-SCM-Datenbank (Service Control Manager). Der Dienst muss zuvor gestoppt worden sein, andernfalls schlägt die Funktion fehl. Die Funktion gehört zur PECL-Erweiterung win32service und steht ausschließlich unter Windows zur Verfügung.
Typischerweise wird diese Funktion in Installations- oder Deinstallationsskripten verwendet, die PHP-Skripte als Windows-Dienste registrieren und wieder entfernen. Der Rückgabewert entspricht einem WIN32-Fehlercode, wobei WIN32_NO_ERROR (0) Erfolg signalisiert.
Ab Version 1.0.0 der win32service-Erweiterung wirft die Funktion bei Fehlern eine Win32ServiceException statt einen Fehlercode zurückzugeben. Die Kompatibilität des eigenen Codes sollte daher je nach eingesetzter Version der Erweiterung angepasst werden.
- Der Dienst muss gestoppt sein, bevor er gelöscht werden kann.
- Das Skript muss mit administrativen Rechten ausgeführt werden.
- Die Funktion ist nur unter Windows verfügbar.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $servicename Pflicht | string | Der interne Name des Windows-Dienstes, wie er in der SCM-Datenbank registriert ist (nicht der Anzeigename). | |
| $machine | string | null | Der Name des entfernten Rechners, auf dem der Dienst gelöscht werden soll. Wird null oder ein leerer String übergeben, wird der lokale Rechner verwendet. |
Rückgabewert
WIN32_NO_ERROR (0) signalisiert Erfolg. Ab Erweiterungsversion 1.0.0 wird stattdessen eine Win32ServiceException geworfen, wenn ein Fehler auftritt.Beispiele
Dienst stoppen und anschließend löschen
<?php
// Sicherstellen, dass die win32service-Erweiterung geladen ist
if (!extension_loaded('win32service')) {
die('win32service-Erweiterung nicht verfügbar.');
}
$serviceName = 'MeinPHPDienst';
// Dienst zuerst stoppen
$stopResult = win32_stop_service($serviceName);
if ($stopResult !== WIN32_NO_ERROR) {
echo "Fehler beim Stoppen des Dienstes: " . $stopResult . PHP_EOL;
exit(1);
}
// Kurz warten, bis der Dienst vollständig gestoppt ist
sleep(3);
// Dienst aus der SCM-Datenbank löschen
$deleteResult = win32_delete_service($serviceName);
if ($deleteResult === WIN32_NO_ERROR) {
echo "Dienst '" . $serviceName . "' wurde erfolgreich gelöscht." . PHP_EOL;
} else {
echo "Fehler beim Löschen des Dienstes. Fehlercode: " . $deleteResult . PHP_EOL;
}Löschen mit Exception-Handling (ab win32service 1.0.0)
<?php
$serviceName = 'MeinPHPDienst';
try {
// Dienst stoppen
win32_stop_service($serviceName);
sleep(3);
// Dienst löschen
win32_delete_service($serviceName);
echo "Dienst erfolgreich gelöscht." . PHP_EOL;
} catch (Win32ServiceException $e) {
echo "Fehler: " . $e->getMessage() . " (Code: " . $e->getCode() . ")" . PHP_EOL;
}// Wichtig · Fallstricke
Administratorrechte erforderlich: Das ausführende PHP-Skript muss mit Administrator-Privilegien gestartet werden, da der Zugriff auf den SCM entsprechende Berechtigungen erfordert. Andernfalls schlägt die Funktion mit einem Zugriffsfehler (ERROR_ACCESS_DENIED) fehl.
Dienst muss gestoppt sein: Ein noch laufender Dienst kann nicht gelöscht werden. Es ist notwendig, den Dienst zuerst mit win32_stop_service() zu stoppen und auf den vollständigen Stopp zu warten, bevor win32_delete_service() aufgerufen wird.
Nur Windows: Diese Funktion ist ausschließlich auf Windows-Systemen verfügbar und erfordert die PECL-Erweiterung win32service. Der Aufruf unter anderen Betriebssystemen führt zu einem fatalen Fehler.
Versionsunterschiede: Ab Version 1.0.0 der win32service-Erweiterung werden Fehler als Win32ServiceException geworfen statt als Fehlercode zurückgegeben. Skripte sollten entsprechend angepasst werden.