Signatur
Beschreibung
win32_start_service() sendet einen Startbefehl an den Windows Service Control Manager (SCM) für den angegebenen Dienst. Die Funktion ist Teil der win32service-PECL-Erweiterung und steht ausschließlich auf Windows-Systemen zur Verfügung.
Der Dienst muss zuvor installiert sein (z. B. mit win32_create_service()). Der Rückgabewert ist ein Windows-Fehlercode: WIN32_NO_ERROR (0) signalisiert Erfolg, jeder andere Wert steht für einen spezifischen Systemfehler. Mit win32_strerror() lässt sich der Fehlercode in eine lesbare Meldung umwandeln.
Ab Version 0.2.0 der win32service-Erweiterung wirft die Funktion bei einem Fehler eine Win32ServiceException statt lediglich einen Fehlercode zurückzugeben – der Code muss entsprechend angepasst werden.
Für den Start eines Dienstes auf einem entfernten Rechner sind ausreichende Berechtigungen erforderlich. In der Regel muss das ausführende PHP-Skript unter einem Konto mit Administratorrechten laufen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $servicename Pflicht | string | Der interne Name des Windows-Dienstes (nicht der Anzeigename), wie er im Dienste-Manager oder in der Registry unter HKLM\SYSTEM\CurrentControlSet\Services eingetragen ist. |
|
| $machine | string | null | Der Name des entfernten Rechners, auf dem der Dienst gestartet werden soll (z. B. \\\\remotehost). Wird null oder ein leerer String übergeben, wird der lokale Rechner verwendet. |
Rückgabewert
WIN32_NO_ERROR (0) bei Erfolg zurück. Bei einem Fehler wird ein Windows-Fehlercode als Integer zurückgegeben. Ab win32service 0.2.0 wird stattdessen eine Win32ServiceException geworfen.Beispiele
Einen lokalen Windows-Dienst starten
<?php
if (!extension_loaded('win32service')) {
die('Die win32service-Erweiterung ist nicht geladen.');
}
$serviceName = 'MyCustomService';
try {
$result = win32_start_service($serviceName);
if ($result === WIN32_NO_ERROR) {
echo "Dienst '{$serviceName}' wurde erfolgreich gestartet.\n";
} else {
echo "Fehler beim Starten des Dienstes: " . win32_strerror($result) . " (Code: {$result})\n";
}
} catch (Win32ServiceException $e) {
echo "Exception beim Starten des Dienstes: " . $e->getMessage() . "\n";
}Dienst auf einem entfernten Rechner starten
<?php
if (!extension_loaded('win32service')) {
die('Die win32service-Erweiterung ist nicht geladen.');
}
$serviceName = 'Spooler';
$remoteMachine = '\\\\PRINTSERVER01';
try {
$result = win32_start_service($serviceName, $remoteMachine);
if ($result === WIN32_NO_ERROR) {
echo "Druckspooler auf {$remoteMachine} wurde gestartet.\n";
} else {
echo "Fehler (" . $result . "): " . win32_strerror($result) . "\n";
}
} catch (Win32ServiceException $e) {
echo "Fehler: " . $e->getMessage() . "\n";
}// Wichtig · Fallstricke
Plattformbeschränkung: Diese Funktion ist ausschließlich unter Windows verfügbar und erfordert die PECL-Erweiterung win32service. Auf Linux/macOS-Systemen ist sie nicht verfügbar.
Berechtigungen: Das PHP-Skript muss mit ausreichenden Windows-Berechtigungen ausgeführt werden (in der Regel Administratorrechte), um Dienste starten zu können. Andernfalls gibt die Funktion den Fehlercode ERROR_ACCESS_DENIED zurück bzw. wirft eine entsprechende Exception.
API-Änderung ab Version 0.2.0: Ab win32service 0.2.0 wird bei Fehlern eine Win32ServiceException geworfen. Älterer Code, der nur den Rückgabewert prüft, muss mit einem try/catch-Block nachgerüstet werden.
Asynchrones Starten: Der Befehl startet den Dienst asynchron – die Funktion kehrt zurück, bevor der Dienst vollständig hochgefahren ist. Um den tatsächlichen Zustand zu prüfen, sollte win32_query_service_status() verwendet werden.