chdir()

Die PHP-Funktion chdir() ändert das aktuelle Arbeitsverzeichnis Ihres Skripts auf das Verzeichnis, das Sie ihr übergeben. Diese Seite erklärt, was das Arbeitsverzeichnis ist, die genaue Signatur von chdir(), wie der Rückgabewert ausgewertet wird und welche häufigen Fälle und Stolpersteine im echten Code auftreten.

Was ist das Arbeitsverzeichnis?

Das aktuelle Arbeitsverzeichnis (CWD) ist der Basispfad, den PHP zur Auflösung relativer Pfade verwendet. Wenn Sie etwas wie fopen('data.txt', 'r') oder include 'config.php' aufrufen, verknüpft PHP diesen relativen Pfad mit dem CWD, um die gemeinte Datei zu ermitteln.

Ein weit verbreiteter Irrtum ist, dass das CWD immer dem Ordner des ausgeführten Skripts entspricht. Das ist nur bei manchen Setups der Ausgangspunkt. Das CWD kann vom Skriptverzeichnis abweichen — zum Beispiel wenn ein Skript durch cron, einen Webserver oder aus einem anderen Arbeitsverzeichnis auf der Kommandozeile gestartet wird. Wenn der Pfad wichtig ist, niemals annehmen; lesen Sie ihn mit getcwd() aus.

Syntax

chdir(string $directory): bool

• $directory — der Pfad, zu dem gewechselt werden soll. Er kann absolut (/var/www/html) oder relativ zum aktuellen CWD (../logs) sein.
• Rückgabewert — true bei Erfolg, false bei Fehler (z. B. wenn das Verzeichnis nicht existiert oder dem Prozess die Berechtigung fehlt). chdir() gibt bei Fehler ein E_WARNING aus, daher sollten Sie den Rückgabewert prüfen und nicht ignorieren.

Grundlegende Verwendung

<?php
// Where are we now?
echo getcwd() . PHP_EOL;   // e.g. /var/www/html

// Move into a subdirectory
chdir('logs');
echo getcwd() . PHP_EOL;   // e.g. /var/www/html/logs

// Move back up one level
chdir('..');
echo getcwd() . PHP_EOL;   // e.g. /var/www/html

Da chdir() relative Pfade akzeptiert, wird chdir('logs') relativ zur aktuellen Position aufgelöst, während chdir('..') ein Verzeichnis nach oben wechselt.

Immer den Rückgabewert prüfen

Ein fehlgeschlagenes chdir() lässt das CWD unverändert, was alle nachfolgenden relativen Pfade stillschweigend brechen kann. Sichern Sie den Aufruf ab:

<?php
$target = '/path/that/may/not/exist';

if (chdir($target)) {
    echo "Now working in: " . getcwd() . PHP_EOL;
} else {
    echo "Could not change to {$target}" . PHP_EOL;
}

Ursprüngliches Verzeichnis speichern und wiederherstellen

Das Ändern des CWD betrifft den gesamten Prozess, nicht nur die aktuelle Funktion. Wenn eine Hilfsfunktion das Verzeichnis wechselt und vergisst, zurückzuwechseln, kann späterer Code falsche Dateien lesen oder schreiben. Ein sicheres Muster ist es, das ursprüngliche Verzeichnis zu speichern und nach getaner Arbeit wiederherzustellen:

<?php
$original = getcwd();      // remember where we started

chdir('/tmp');
// ... do work that relies on /tmp being the CWD ...

chdir($original);          // restore for the rest of the script
echo getcwd() . PHP_EOL;   // back to where we started

chdir() in Kombination mit Includes

Sobald das CWD geändert wurde, werden relative include/require-Pfade vom neuen Ort aus aufgelöst:

<?php
chdir('/path/to/app/config');
include 'database.php';   // resolves to /path/to/app/config/database.php

Bei Includes ist die Abhängigkeit vom CWD fragil, da Aufrufer es ändern können. Bevorzugen Sie einen absoluten Pfad, der aus dem Speicherort des Skripts selbst mit der magischen Konstante __DIR__ aufgebaut wird:

<?php
// Robust regardless of the current working directory
include __DIR__ . '/config/database.php';

Wann würde ich chdir() verwenden?

• CLI-Skripte und Build-Tools, die Befehle ausführen, die ein bestimmtes Verzeichnis erwarten.
• Batch-Jobs (via cron ausgeführt), bei denen das startende CWD unvorhersehbar ist, sodass Sie es vorher explizit setzen.
• Arbeiten mit relativen Pfaden in großen Mengen — z. B. das Durchlaufen von Dateien in einem Ordner, ohne jeden Pfad mit einem Präfix zu versehen.

Für die meisten Webanwendungen sollten Sie absolute Pfade (__DIR__, konfigurierte Basispfade) dem Ändern des globalen CWD vorziehen, da die Änderung den gesamten Request betrifft.

Verwandte Funktionen

• getcwd() — das aktuelle Arbeitsverzeichnis auslesen.
• mkdir() — ein Verzeichnis erstellen, bevor man hineinwechselt.
• scandir() / opendir() — den Inhalt eines Verzeichnisses auflisten.
• realpath() — einen relativen Pfad in seine absolute, symlink-aufgelöste Form umwandeln.
• dirname() — den Verzeichnisanteil eines Pfad-Strings ermitteln.

Übung