win32_start_service_ctrl_dispatcher — Funktion · PHP-Referenz

Signatur

win32_start_service_ctrl_dispatcher(string $name, bool $graceful_mode = true): void

Beschreibung

win32_start_service_ctrl_dispatcher() ist der Einstiegspunkt für ein PHP-Skript, das als Windows-Dienst laufen soll. Diese Funktion meldet das Skript beim Service Control Manager (SCM) an und übergibt die Kontrolle an diesen. Sie muss als erste Funktion im Dienstskript aufgerufen werden, bevor irgendwelche eigentliche Logik ausgeführt wird.

Nach dem Aufruf erwartet der SCM, dass das Skript regelmäßig Statusinformationen über Funktionen wie win32_set_service_status() liefert. Ohne korrekte Statuspflege kann Windows den Dienst als nicht reagierend einstufen und ihn beenden.

Der Parameter $name muss exakt dem Dienstnamen entsprechen, der zuvor mit win32_create_service() registriert wurde. Tritt ein Fehler auf, weil der Dienstname nicht gefunden wird oder das Skript nicht aus dem Kontext des SCM gestartet wurde, wird eine Ausnahme vom Typ Win32ServiceException geworfen (ab Version 1.0.0 der PECL-Erweiterung).

Diese Funktion ist ausschließlich auf Windows-Systemen verfügbar und erfordert die PECL-Erweiterung win32service. Sie wird typischerweise in Kombination mit win32_create_service(), win32_set_service_status() und win32_query_service_status() eingesetzt, um vollständige Windows-Dienste in PHP zu implementieren.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Der Name des Windows-Dienstes, unter dem das Skript beim SCM registriert werden soll. Muss exakt mit dem Namen übereinstimmen, der bei der Dienst-Erstellung verwendet wurde.
$graceful_mode	bool	true	Wenn `true`, wird bei einem Fehler eine `Win32ServiceException` geworfen statt `false` zurückzugeben. Betrifft das Fehlerbehandlungsverhalten ab neueren Versionen der PECL-Erweiterung.

Rückgabewert

Typ

void

Beschreibung

Gibt keinen Wert zurück. Bei einem Fehler (z. B. unbekannter Dienstname oder kein SCM-Kontext) wird eine Win32ServiceException geworfen, sofern $graceful_mode auf true gesetzt ist.

Beispiele

Grundlegendes Windows-Dienst-Skript

<?php
// Dienst-Einstiegspunkt: Diese Datei wird vom SCM als Dienst gestartet

if (!defined('PHP_WINDOWS_VERSION_MAJOR')) {
    die('Dieses Skript läuft nur unter Windows.');
}

// Dienstnamen beim SCM registrieren
try {
    win32_start_service_ctrl_dispatcher('MeinPHPDienst');
} catch (Win32ServiceException $e) {
    error_log('Fehler beim Registrieren des Dienstes: ' . $e->getMessage());
    exit(1);
}

// Dienst als gestartet melden
win32_set_service_status(WIN32_SERVICE_RUNNING);

$running = true;

while ($running) {
    // Auf SCM-Steuerbefehle prüfen
    $status = win32_get_last_control_message();

    if ($status === WIN32_SERVICE_CONTROL_STOP ||
        $status === WIN32_SERVICE_CONTROL_SHUTDOWN) {
        $running = false;
    }

    // Eigentliche Dienst-Logik hier
    // z. B. Dateien verarbeiten, Datenbank abfragen etc.

    sleep(5);
}

// Dienst sauber beenden
win32_set_service_status(WIN32_SERVICE_STOPPED);

Dienst erstellen und registrieren

<?php
// Einmalige Registrierung des Dienstes im System (z. B. per Installations-Skript)
$serviceConfig = [
    'service'     => 'MeinPHPDienst',
    'display'     => 'Mein PHP Hintergrunddienst',
    'description' => 'Verarbeitet Hintergrundaufgaben mit PHP',
    'params'      => 'C:\\dienste\\mein_dienst.php',
    'path'        => 'C:\\php\\php.exe',
    'user'        => '',
    'password'    => '',
    'start_type'  => WIN32_SERVICE_AUTO_START,
];

try {
    win32_create_service($serviceConfig);
    echo "Dienst erfolgreich registriert.\n";
} catch (Win32ServiceException $e) {
    echo "Fehler: " . $e->getMessage() . "\n";
}

// Dienst starten
try {
    win32_start_service('MeinPHPDienst');
    echo "Dienst gestartet.\n";
} catch (Win32ServiceException $e) {
    echo "Startfehler: " . $e->getMessage() . "\n";
}

Dienst erfolgreich registriert. Dienst gestartet.

// Wichtig · Fallstricke

Nur Windows: Diese Funktion ist ausschließlich unter Windows verfügbar und erfordert die PECL-Erweiterung win32service, die separat installiert werden muss (pecl install win32service).

Aufruf-Reihenfolge: win32_start_service_ctrl_dispatcher() muss der erste Aufruf im Skript sein. Jegliche Ausgabe (z. B. echo) oder Fehler vor diesem Aufruf können dazu führen, dass der SCM den Dienst als fehlerhaft betrachtet.

Ausführungskontext: Das Skript muss vom SCM gestartet werden, nicht direkt über die Kommandozeile. Ein direkter Start über php mein_dienst.php führt zu einem Fehler, da kein SCM-Kontext vorhanden ist.

Fehlerbehandlung: Ab Version 1.0.0 der PECL-Erweiterung wird anstelle von Fehlercodes eine Win32ServiceException geworfen. Älterer Code, der Rückgabewerte prüft, muss entsprechend angepasst werden.

Siehe auch

win32_create_service win32_set_service_status win32_get_last_control_message win32_start_service win32_stop_service win32_query_service_status