putenv — Funktion · PHP-Referenz

Signatur

putenv(string $assignment): bool

Beschreibung

putenv() ermöglicht es, zur Laufzeit Umgebungsvariablen im aktuellen PHP-Prozess zu setzen oder zu ändern. Die Änderung ist nur für die Dauer des aktuellen Requests gültig und wird nicht dauerhaft in der Systemumgebung gespeichert. Der Parameter assignment muss im Format NAME=Wert übergeben werden.

Typische Einsatzszenarien sind das Setzen von PATH-Erweiterungen für externe Programme, die per exec() oder shell_exec() aufgerufen werden, oder das Übergeben von Konfigurationswerten an Kindprozesse, die über proc_open() gestartet werden.

Mit putenv('VAR=') kann man eine Variable auf einen leeren String setzen. Um eine Variable vollständig zu löschen, übergibt man nur den Variablennamen ohne Gleichheitszeichen: putenv('VAR'). Gesetzt werden die Variablen können anschließend mit getenv() ausgelesen werden.

Wichtig: Änderungen über putenv() beeinflussen nur die Umgebung des aktuellen PHP-Prozesses und seiner Kindprozesse – niemals den übergeordneten Webserver-Prozess oder andere parallele Requests.

Parameter

Name	Typ	Default	Beschreibung
$assignment Pflicht	string		Eine Zeichenkette im Format `NAME=Wert` zum Setzen der Variablen, oder nur `NAME` (ohne Gleichheitszeichen) zum Entfernen der Variablen aus der Umgebung.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Umgebungsvariable erfolgreich gesetzt wurde, andernfalls false. Ein Fehlschlag kann auftreten, wenn die Umgebung schreibgeschützt ist oder der übergebene String ungültig ist.

Beispiele

Umgebungsvariable setzen und auslesen

<?php
// Umgebungsvariable setzen
$success = putenv('APP_ENV=production');

if ($success) {
    echo getenv('APP_ENV'); // Gibt 'production' aus
} else {
    echo 'Fehler beim Setzen der Umgebungsvariablen.';
}

production

PATH-Variable für externen Programmaufruf erweitern

<?php
// Aktuellen PATH auslesen und erweitern
$currentPath = getenv('PATH');
putenv('PATH=' . $currentPath . ':/usr/local/myapp/bin');

// Jetzt kann ein externes Programm unter /usr/local/myapp/bin gefunden werden
$output = shell_exec('myprogramm --version');
echo $output;

Umgebungsvariable wieder entfernen

<?php
// Variable setzen
putenv('TEMP_TOKEN=abc123');
echo getenv('TEMP_TOKEN') . PHP_EOL; // abc123

// Variable entfernen (kein '=' und kein Wert)
putenv('TEMP_TOKEN');
var_dump(getenv('TEMP_TOKEN')); // false, da nicht mehr gesetzt

abc123 bool(false)

// Wichtig · Fallstricke

Sicherheitshinweis: Benutzereingaben sollten niemals ungefiltert an putenv() übergeben werden. Angreifer könnten darüber kritische Umgebungsvariablen wie LD_PRELOAD oder LD_LIBRARY_PATH manipulieren und so beliebigen Code einschleusen.

In Thread-Safe-Umgebungen (z. B. unter Apache mit dem Worker-MPM) kann putenv() zu Problemen führen, da Umgebungsvariablen global im Prozess gesetzt werden und dadurch andere Threads beeinflusst werden könnten. In solchen Szenarien sollte man alternative Konfigurationsmechanismen bevorzugen.

Die Funktion getenv() gibt standardmäßig auch via putenv() gesetzte Variablen zurück. Seit PHP 7.1 akzeptiert getenv() aber einen zweiten Parameter $local_only, mit dem nur prozesslokale Variablen abgerufen werden können.

Siehe auch

getenv proc_open shell_exec exec