Signatur
Beschreibung
win32_create_service() registriert einen neuen Windows-Dienst in der SCM-Datenbank (Service Control Manager). Damit lässt sich ein PHP-Skript als dauerhaft laufender Windows-Dienst einrichten, der beim Systemstart automatisch gestartet werden kann und über die Windows-Dienstverwaltung (services.msc) oder die Kommandozeile steuerbar ist.
Der erste Parameter $details ist ein assoziatives Array, das alle relevanten Eigenschaften des Dienstes beschreibt, wie den internen Dienstnamen, den Anzeigenamen, den Pfad zur ausführbaren Datei, den Starttyp sowie den Benutzer, unter dem der Dienst läuft. Der optionale Parameter $machine erlaubt es, den Dienst auf einem entfernten Rechner zu registrieren.
Ab win32service 1.0.0 wirft die Funktion im Fehlerfall eine Win32ServiceException, in älteren Versionen gab sie einen Fehlercode zurück. Die Funktion erfordert administrative Rechte, da das Schreiben in die SCM-Datenbank entsprechende Berechtigungen voraussetzt.
Typischer Anwendungsfall ist die Einrichtung eines PHP-basierten Daemon-Prozesses, z. B. für Hintergrundverarbeitung, Queue-Worker oder Überwachungsdienste auf Windows-Servern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $details Pflicht | array | Assoziatives Array mit den Dienstdetails. Wichtige Schlüssel:
|
|
| $machine | string | null | Name oder IP-Adresse des Zielrechners, auf dem der Dienst registriert werden soll. Wird null übergeben oder der Parameter weggelassen, wird der lokale Rechner verwendet. |
Rückgabewert
Ab win32service 1.0.0: Gibt nichts zurück; bei einem Fehler wird eine Win32ServiceException geworfen.
In älteren Versionen (vor 1.0.0): Gibt WIN32_NO_ERROR (0) bei Erfolg zurück, andernfalls einen Windows-Fehlercode.
Beispiele
Einfachen PHP-Worker-Dienst registrieren
<?php
// Dienst als Administrator registrieren
$details = [
'service' => 'MyPHPWorker',
'display' => 'Mein PHP Worker-Dienst',
'description' => 'Verarbeitet Hintergrund-Jobs via PHP.',
'path' => 'C:\\php\\php.exe',
'params' => 'C:\\inetpub\\worker\\worker.php',
'start_type' => WIN32_SERVICE_AUTO_START,
'user' => 'LocalSystem',
'password' => '',
];
try {
win32_create_service($details);
echo "Dienst erfolgreich registriert.\n";
} catch (Win32ServiceException $e) {
echo "Fehler beim Registrieren: " . $e->getMessage() . "\n";
}Dienst mit Abhängigkeiten und Wiederherstellungsoptionen
<?php
$details = [
'service' => 'MyQueueService',
'display' => 'PHP Queue Processor',
'description' => 'Liest und verarbeitet Nachrichten aus einer Queue.',
'path' => 'C:\\php\\php.exe',
'params' => 'C:\\app\\queue_worker.php',
'start_type' => WIN32_SERVICE_AUTO_START,
'error_control' => WIN32_SERVER_ERROR_NORMAL,
'user' => '.\\ServiceUser',
'password' => 'SicheresPasswort!123',
'dependencies' => ['MSSQLSERVER', 'Tcpip'],
'recovery_delay' => 5000,
'recovery_action_1' => WIN32_SC_ACTION_RESTART,
'recovery_action_2' => WIN32_SC_ACTION_RESTART,
'recovery_action_3' => WIN32_SC_ACTION_NONE,
];
try {
win32_create_service($details);
echo "Dienst 'MyQueueService' wurde erfolgreich in der SCM-Datenbank eingetragen.\n";
} catch (Win32ServiceException $e) {
fprintf(STDERR, "SCM-Fehler [%d]: %s\n", $e->getCode(), $e->getMessage());
exit(1);
}// Wichtig · Fallstricke
Administratorrechte erforderlich: win32_create_service() schreibt in die Windows-Registrierung und die SCM-Datenbank. Das ausführende PHP-Skript muss daher mit erhöhten Rechten (als Administrator) laufen, sonst schlägt der Aufruf mit einem Zugriffsfehler fehl.
Nur unter Windows verfügbar: Die Funktion ist ausschließlich im PECL-Paket win32service vorhanden und funktioniert nur auf Windows-Systemen. Eine Verwendung unter Linux oder macOS ist nicht möglich.
Bereits vorhandener Dienst: Existiert ein Dienst mit demselben Namen (service-Schlüssel) bereits, schlägt der Aufruf fehl. Verwende zunächst win32_delete_service(), um den alten Eintrag zu entfernen.
Sicherheitshinweis: Speichere Passwörter für Dienstkonten niemals im Klartext im Quellcode. Nutze Umgebungsvariablen oder sichere Konfigurationsdateien außerhalb des Webroot.
API-Änderung in 1.0.0: Ab Version 1.0.0 des win32service-Pakets gibt die Funktion void zurück und wirft bei Fehlern eine Win32ServiceException statt eines Integer-Fehlercodes.