dir — Funktion · PHP-Referenz · programmierung.net

Signatur

dir(string $directory, ?resource $context = null): Directory|false

Beschreibung

dir() ist eine objektorientierte Alternative zu opendir(). Die Funktion öffnet das angegebene Verzeichnis und gibt ein Objekt der Klasse Directory zurück. Dieses Objekt stellt drei Mitglieder bereit: die Eigenschaft path (der Pfad des geöffneten Verzeichnisses), die Eigenschaft handle (das interne Verzeichnis-Handle) sowie die Methoden read(), rewind() und close().

Die Methode read() liefert nacheinander die Namen aller Einträge im Verzeichnis (einschließlich . und ..) und gibt false zurück, wenn keine weiteren Einträge vorhanden sind. Mit rewind() wird der Lesezeiger auf den Anfang zurückgesetzt, und close() schließt das Verzeichnis-Handle.

Der optionale Parameter context erlaubt die Übergabe eines Stream-Kontexts, etwa um Verzeichnisse auf entfernten Dateisystemen (z. B. FTP oder SSH2) zu öffnen. Für lokale Verzeichnisse wird dieser Parameter in der Regel weggelassen.

Gegenüber der prozeduralen Variante mit opendir()/readdir() bietet dir() einen saubereren, objektorientierten Stil und ist besonders praktisch, wenn mehrere Verzeichnisse gleichzeitig geöffnet werden.

Parameter

Name	Typ	Default	Beschreibung
$directory Pflicht	string		Pfad zu dem Verzeichnis, das geöffnet werden soll. Kann ein absoluter oder relativer Pfad sein.
$context	resource\|null	null	Optionaler Stream-Kontext, der mit `stream_context_create()` erzeugt wurde. Wird für Netzwerk-Dateisysteme oder spezielle Wrapper benötigt.

Rückgabewert

Typ

Directory|false

Beschreibung

Gibt bei Erfolg eine Instanz der Klasse Directory zurück. Wenn das Verzeichnis nicht geöffnet werden kann (z. B. weil es nicht existiert oder die Rechte fehlen), wird false zurückgegeben und ein Fehler der Stufe E_WARNING ausgelöst.

Beispiele

Alle Einträge eines Verzeichnisses auflisten

<?php
$d = dir('/var/www/html');

if ($d === false) {
    echo 'Verzeichnis konnte nicht geöffnet werden.';
    exit;
}

echo 'Pfad: ' . $d->path . PHP_EOL;

while (($entry = $d->read()) !== false) {
    echo $entry . PHP_EOL;
}

$d->close();

Pfad: /var/www/html . .. index.php config.php assets

Nur reguläre Dateien (ohne . und ..) anzeigen

<?php
$verzeichnis = __DIR__ . '/uploads';
$d = dir($verzeichnis);

if ($d === false) {
    throw new RuntimeException('Verzeichnis nicht lesbar: ' . $verzeichnis);
}

$dateien = [];

while (($eintrag = $d->read()) !== false) {
    if ($eintrag === '.' || $eintrag === '..') {
        continue;
    }
    $vollerPfad = $verzeichnis . DIRECTORY_SEPARATOR . $eintrag;
    if (is_file($vollerPfad)) {
        $dateien[] = $eintrag;
    }
}

$d->close();

sort($dateien);
foreach ($dateien as $datei) {
    echo $datei . PHP_EOL;
}

bild.jpg dokument.pdf logo.png

// Wichtig · Fallstricke

Reihenfolge der Einträge: Die Reihenfolge, in der read() die Einträge liefert, ist vom Dateisystem abhängig und kann nicht garantiert werden. Für eine sortierte Ausgabe müssen die Einträge in einem Array gesammelt und dann sortiert werden.

Fehlerbehandlung: Wenn ein ungültiger Pfad übergeben wird, gibt dir() false zurück und wirft eine E_WARNING. Den Rückgabewert stets auf false prüfen oder set_error_handler() bzw. einen eigenen Stream-Wrapper nutzen.

Handle schließen: Das Verzeichnis-Handle sollte nach der Verwendung immer mit $d->close() geschlossen werden, um Ressourcen freizugeben – insbesondere in lang laufenden Skripten oder Schleifen über viele Verzeichnisse.

Siehe auch

opendir readdir closedir rewinddir scandir glob Directory