apache_setenv — Funktion · PHP-Referenz

Signatur

apache_setenv(string $variable, string $value, bool $walk_to_top = false): bool

Beschreibung

apache_setenv() setzt eine Umgebungsvariable im Apache-internen subprocess_env-Bereich. Diese Variablen sind nicht identisch mit den PHP-Umgebungsvariablen ($_ENV), sondern werden direkt in den Apache-Request-Record geschrieben und stehen damit z. B. anderen Apache-Modulen, CGI-Skripten oder nachgelagerten Prozessen zur Verfügung.

Der optionale Parameter walk_to_top bestimmt, ob die Variable im obersten verfügbaren request_rec-Knoten gesetzt werden soll. Ist er true, wird der Wert in den Haupt-Request (Top-Level-Request) geschrieben statt in den Sub-Request, was bei internen Umleitungen relevant sein kann.

Typische Einsatzgebiete sind das Weitergeben von Informationen aus PHP an Apache-Module wie mod_rewrite, mod_headers oder Logging-Module, ohne dabei die tatsächliche PHP-Umgebung (putenv()) zu verändern.

Wichtig: Diese Funktion ist nur verfügbar, wenn PHP als Apache-Modul (mod_php) läuft. Unter PHP-FPM, CLI oder anderen SAPIs steht sie nicht zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$variable Pflicht	string		Name der Apache-Subprocess-Umgebungsvariable, die gesetzt werden soll.
$value Pflicht	string		Wert, der der Variablen zugewiesen werden soll.
$walk_to_top	bool	false	Wenn `true`, wird die Variable im übergeordneten (Top-Level-)Request-Record gesetzt statt im aktuellen Sub-Request.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Variable erfolgreich gesetzt wurde, andernfalls false.

Beispiele

Einfaches Setzen einer Apache-Umgebungsvariable

<?php
// Setzt die Apache-Subprocess-Variable 'APP_USER' auf 'johndoe'
if (apache_setenv('APP_USER', 'johndoe')) {
    echo 'Variable erfolgreich gesetzt.';
} else {
    echo 'Fehler beim Setzen der Variable.';
}
// Die Variable kann z. B. in Apache-Log-Formaten via %{APP_USER}e abgerufen werden

Variable erfolgreich gesetzt.

Variable im Top-Level-Request setzen (bei internen Weiterleitungen)

<?php
// Beim Einsatz mit internen Apache-Weiterleitungen (z. B. via ErrorDocument)
// walk_to_top = true stellt sicher, dass die Variable im Haupt-Request landet
$success = apache_setenv('PHP_PROCESSED', '1', true);

if ($success) {
    echo 'Variable im Top-Level-Request gesetzt.';
}

// Kann dann im Apache-Zugriffslog per CustomLog-Direktive ausgelesen werden:
// LogFormat "%h %l %u %t \"%r\" %>s %{PHP_PROCESSED}e" combined

Variable im Top-Level-Request gesetzt.

// Wichtig · Fallstricke

SAPI-Abhängigkeit: apache_setenv() ist ausschließlich unter dem Apache-SAPI (mod_php) verfügbar. Beim Einsatz unter PHP-FPM, CLI oder anderen Web-Servern führt der Aufruf zu einem fatalen Fehler (Call to undefined function). Prüfe die Verfügbarkeit ggf. mit function_exists('apache_setenv').

Kein Einfluss auf $_ENV oder getenv(): Die gesetzte Variable ist nicht über getenv() oder $_ENV in PHP abrufbar. Für PHP-seitige Umgebungsvariablen muss stattdessen putenv() verwendet werden.

Sicherheit: Setze niemals unkontrollierte Benutzereingaben als Variablenname oder -wert, da diese Werte an Apache-Module weitergegeben werden und dort unerwartetes Verhalten auslösen könnten.

Siehe auch

apache_getenv apache_request_headers putenv getenv apache_note