Signatur
Beschreibung
win32_add_service_env_var() ermöglicht es, einem registrierten Windows-Dienst eine Umgebungsvariable zuzuweisen, bevor der Dienst gestartet wird. Die Variable wird persistent in der Windows-Dienstkonfiguration gespeichert und steht dem Dienstprozess bei jedem Start zur Verfügung.
Diese Funktion ist Teil der win32service-PECL-Erweiterung und steht ausschließlich auf Windows-Systemen zur Verfügung. Sie ist nützlich, wenn ein PHP-Dienst bestimmte Konfigurationswerte wie Pfade, Verbindungsstrings oder Flags über Umgebungsvariablen empfangen soll, ohne dass diese in Code oder Konfigurationsdateien fest eingebettet werden müssen.
Die Funktion muss aufgerufen werden, bevor der Dienst mit win32_start_service() gestartet wird, typischerweise im Rahmen der Dienst-Registrierung oder -Konfiguration. Für die Ausführung sind in der Regel administrative Rechte auf dem System erforderlich.
- Die gesetzten Umgebungsvariablen gelten nur für den jeweiligen Dienst, nicht systemweit.
- Mehrere Variablen können durch wiederholtes Aufrufen der Funktion hinzugefügt werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $servicename Pflicht | string | Der interne Name des Windows-Dienstes, dem die Umgebungsvariable hinzugefügt werden soll. Dieser Name muss mit dem bei win32_create_service() verwendeten Dienstnamen übereinstimmen. |
|
| $name Pflicht | string | Der Name der Umgebungsvariable, z. B. APP_ENV oder DB_HOST. Groß-/Kleinschreibung wird unter Windows bei Umgebungsvariablen üblicherweise nicht unterschieden. |
|
| $value Pflicht | string | Der Wert, der der Umgebungsvariable zugewiesen werden soll, z. B. production oder localhost. |
Rückgabewert
Win32ServiceException ausgelöst.Beispiele
Umgebungsvariable bei der Dienst-Registrierung setzen
<?php
// Dienst registrieren
$result = win32_create_service([
'service' => 'MyPHPService',
'display' => 'Mein PHP-Dienst',
'description' => 'Ein Beispieldienst in PHP',
'params' => 'C:\\php\\php.exe C:\\services\\myservice.php',
]);
if ($result !== WIN32_NO_ERROR) {
die('Dienst konnte nicht registriert werden. Fehlercode: ' . $result);
}
// Umgebungsvariablen hinzufügen
win32_add_service_env_var('MyPHPService', 'APP_ENV', 'production');
win32_add_service_env_var('MyPHPService', 'DB_HOST', 'localhost');
win32_add_service_env_var('MyPHPService', 'DB_PORT', '3306');
echo 'Dienst registriert und Umgebungsvariablen gesetzt.' . PHP_EOL;
?>Umgebungsvariable im Dienst auslesen
<?php
// Innerhalb des laufenden Dienstprozesses (myservice.php)
win32_start_service_ctrl_dispatcher('MyPHPService');
win32_set_service_status(WIN32_SERVICE_RUNNING);
$appEnv = getenv('APP_ENV');
$dbHost = getenv('DB_HOST');
echo 'Umgebung: ' . $appEnv . PHP_EOL;
echo 'Datenbank-Host: ' . $dbHost . PHP_EOL;
// Dienst-Hauptschleife
while (WIN32_SERVICE_CONTROL_STOP !== win32_get_last_control_message()) {
// Dienstlogik
sleep(1);
}
win32_set_service_status(WIN32_SERVICE_STOPPED);
?>// Wichtig · Fallstricke
Plattformabhängigkeit: Diese Funktion ist ausschließlich unter Windows verfügbar und erfordert die win32service-PECL-Erweiterung. Ein Aufruf auf anderen Betriebssystemen führt zu einem fatalen Fehler.
Berechtigungen: Zum Hinzufügen von Umgebungsvariablen zu einem Windows-Dienst sind administrative Rechte erforderlich. Das Skript sollte daher mit erhöhten Berechtigungen ausgeführt werden.
Sicherheitshinweis: Sensible Daten wie Passwörter oder API-Schlüssel sollten nicht unverschlüsselt als Umgebungsvariablen gespeichert werden, da diese im Windows-Dienstmanager und in der Registry einsehbar sein können. Erwäge den Einsatz eines sicheren Secret-Managements.
Ab Version 1.0.0 der win32service-Erweiterung wird bei Fehlern eine Win32ServiceException geworfen, anstatt einen Fehlercode zurückzugeben.