chdir — Funktion · PHP-Referenz

Signatur

chdir(string $directory): bool

Beschreibung

chdir() setzt das aktuelle Arbeitsverzeichnis des laufenden PHP-Prozesses auf den übergebenen Pfad. Dies beeinflusst alle nachfolgenden Dateioperationen, die mit relativen Pfaden arbeiten, wie z. B. fopen(), include, require oder glob().

Die Funktion ist besonders nützlich in CLI-Skripten, bei denen man zwischen verschiedenen Verzeichnissen navigieren möchte, ohne überall absolute Pfade angeben zu müssen. Sie kann auch in Kombination mit getcwd() verwendet werden, um das vorherige Verzeichnis zu merken und später dorthin zurückzukehren.

Im Webserver-Kontext (z. B. Apache, FPM) ist das Arbeitsverzeichnis zu Beginn des Requests meist das Dokumentenstamm- oder Skriptverzeichnis. Änderungen mit chdir() wirken sich nur auf den aktuellen Prozess aus und haben keinen Einfluss auf andere gleichzeitig laufende Requests oder Prozesse.

Es empfiehlt sich, den Rückgabewert zu prüfen, da die Funktion false zurückgibt, wenn das Verzeichnis nicht existiert oder keine Leserechte vorhanden sind.

Parameter

Name	Typ	Default	Beschreibung
$directory Pflicht	string		Der Pfad des Verzeichnisses, in das gewechselt werden soll. Kann absolut oder relativ zum aktuellen Arbeitsverzeichnis angegeben werden.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn das Verzeichnis erfolgreich gewechselt wurde. Gibt false zurück, wenn das Verzeichnis nicht existiert, keine ausreichenden Rechte vorhanden sind oder ein anderer Fehler auftritt.

Beispiele

Einfacher Verzeichniswechsel mit Fehlerbehandlung

<?php
$ziel = '/var/www/html/uploads';

if (chdir($ziel)) {
    echo 'Aktuelles Verzeichnis: ' . getcwd() . PHP_EOL;
    // Ab hier können relative Pfade relativ zu /var/www/html/uploads genutzt werden
    $dateien = glob('*.jpg');
    print_r($dateien);
} else {
    echo 'Fehler: Verzeichnis konnte nicht gewechselt werden.' . PHP_EOL;
}

Aktuelles Verzeichnis: /var/www/html/uploads Array ( [0] => foto1.jpg [1] => foto2.jpg )

Vorheriges Verzeichnis merken und wiederherstellen

<?php
// Aktuelles Verzeichnis merken
$ursprung = getcwd();
echo 'Start: ' . $ursprung . PHP_EOL;

// In ein anderes Verzeichnis wechseln
if (chdir('/tmp')) {
    echo 'Aktuell: ' . getcwd() . PHP_EOL;

    // Arbeiten im /tmp-Verzeichnis
    file_put_contents('test.txt', 'Hallo Welt');
    echo 'Datei erstellt: ' . realpath('test.txt') . PHP_EOL;
}

// Zurück zum ursprünglichen Verzeichnis
chdir($ursprung);
echo 'Zurück: ' . getcwd() . PHP_EOL;

Start: /var/www/html Aktuell: /tmp Datei erstellt: /tmp/test.txt Zurück: /var/www/html

// Wichtig · Fallstricke

Sicherheitshinweis: Wenn der an chdir() übergebene Pfad aus Benutzereingaben stammt, muss er sorgfältig validiert und bereinigt werden, um Path-Traversal-Angriffe zu verhindern (z. B. Eingaben wie ../../etc). Verwende realpath() und prüfe, ob der resultierende Pfad innerhalb des erlaubten Basisverzeichnisses liegt.

Im Webserver-Kontext (mod_php) teilen sich mehrere Anfragen denselben Prozess. Da chdir() das Arbeitsverzeichnis prozessweit ändert, kann eine nicht zurückgesetzte Änderung nachfolgende Requests beeinflussen, falls kein ausreichendes Prozess-Isolation-Modell (z. B. PHP-FPM mit separaten Pools) eingesetzt wird. Es empfiehlt sich daher, das ursprüngliche Verzeichnis immer wiederherzustellen.

Siehe auch

getcwd realpath opendir glob scandir