scandir()

Einführung

Die Verzeichnisverwaltung ist ein wesentlicher Bestandteil der PHP-Programmierung — nahezu jedes Backup-Skript, jeder Datei-Uploader oder Asset-Prozessor muss auflisten, was sich in einem Ordner befindet. Dieser Artikel befasst sich eingehend mit der PHP-Funktion scandir(), die den Inhalt eines Verzeichnisses in einem einzigen Aufruf ausliest. Sie erfahren, was sie zurückgibt, wie Sie das Ergebnis sortieren und filtern, wie sie sich von glob() unterscheidet und wie Sie Fehler sicher behandeln.

Was ist scandir?

scandir() liest ein Verzeichnis und gibt die Namen aller enthaltenen Einträge — Dateien und Unterverzeichnisse — als flaches Array von Strings zurück. Das Array enthält immer die beiden Sondereinträge . (das aktuelle Verzeichnis) und .. (das übergeordnete Verzeichnis), sodass Sie diese fast immer herausfiltern, bevor Sie das Ergebnis verwenden.

Wenn das Verzeichnis nicht gelesen werden kann, gibt scandir() false zurück und gibt eine Warnung aus. Die Funktion ist seit PHP 4.3.0 verfügbar und funktioniert sowohl auf Unix-basierten als auch auf Windows-Systemen.

Syntax

scandir(string $directory, int $sorting_order = SCANDIR_SORT_ASCENDING, ?resource $context = null): array|false

Die Funktion gibt bei Erfolg ein Array von Dateinamen zurück oder false bei einem Fehler.

Die Namen werden ohne den Verzeichnispfad zurückgegeben. Um einen verwendbaren Pfad zu erhalten, stellen Sie das Verzeichnis selbst voran: $directory . '/' . $entry.

Wie funktioniert scandir?

In seiner einfachsten Form übergeben Sie nur den Verzeichnispfad. Der Inhalt wird alphabetisch (aufsteigend) zurückgegeben, da dies der Standard-$sorting_order ist. Das folgende Beispiel filtert . und .. mit array_diff() heraus, sodass nur echte Einträge verbleiben:

Beispiel der Funktion scandir() in PHP

<?php

$dir = "/path/to/directory";
$files = scandir($dir);

// Filter out the current and parent directory entries
$filtered = array_diff($files, ['.', '..']);

foreach ($filtered as $file) {
    echo $file . "<br>";
}

Dieser Code zeigt eine Liste von Dateien und Unterverzeichnissen im angegebenen Verzeichnis an, ohne . und ...

Verzeichnisinhalte sortieren

Übergeben Sie ein zweites Argument, um die Reihenfolge des Ergebnisses zu steuern. Die drei Optionen sind:

• SCANDIR_SORT_ASCENDING — alphabetisch A→Z (der Standard).
• SCANDIR_SORT_DESCENDING — alphabetisch Z→A.
• SCANDIR_SORT_NONE — keine Sortierung; Einträge werden in der Reihenfolge zurückgegeben, die das Dateisystem liefert. Dies ist die schnellste Option und lohnt sich, wenn Sie die Liste ohnehin selbst sortieren oder die Reihenfolge keine Rolle spielt.

Bei einem Verzeichnis mit archive.txt, data.csv, report.txt, notes.md, image.png und einem Unterverzeichnis backups:

Wie man die scandir()-Ausgabe in absteigender Reihenfolge sortiert

<?php

$dir = "/path/to/directory";
$files = scandir($dir, SCANDIR_SORT_DESCENDING);

print_r($files);
// Array
// (
//     [0] => report.txt
//     [1] => notes.md
//     [2] => image.png
//     [3] => data.csv
//     [4] => backups
//     [5] => ..
//     [6] => .
// )

Dieselben Daten mit SCANDIR_SORT_NONE werden unsortiert zurückgegeben (die genaue Reihenfolge hängt vom Dateisystem ab), was den kleinen Sortieraufwand vermeidet.

Nur Dateien (oder nur Verzeichnisse) auflisten

scandir() gibt Dateien und Ordner gemischt zurück. Um nur Dateien zu behalten, prüfen Sie jeden Eintrag mit is_file(); um nur Verzeichnisse zu behalten, verwenden Sie is_dir(). Denken Sie daran, zuerst den vollständigen Pfad zu erstellen:

<?php

$dir = "/path/to/directory";
$entries = array_diff(scandir($dir), ['.', '..']);

$filesOnly = array_filter($entries, fn($entry) => is_file($dir . '/' . $entry));

print_r(array_values($filesOnly));
// Array
// (
//     [0] => archive.txt
//     [1] => data.csv
//     [2] => image.png
//     [3] => notes.md
//     [4] => report.txt
// )

Nach Dateiendung filtern

Eine häufige Aufgabe ist es, nur Dateien eines bestimmten Typs zu erfassen. Kombinieren Sie scandir() mit pathinfo(), um die Erweiterung jedes Eintrags auszulesen:

<?php

$dir = "/path/to/directory";
$entries = array_diff(scandir($dir), ['.', '..']);

$textFiles = array_filter(
    $entries,
    fn($entry) => pathinfo($entry, PATHINFO_EXTENSION) === 'txt'
);

print_r(array_values($textFiles));
// Array
// (
//     [0] => archive.txt
//     [1] => report.txt
// )

Wenn Sie Dateien nur anhand eines Musters abgleichen möchten, kann glob() dies in einem Schritt erledigen — zum Beispiel glob("$dir/*.txt") — und gibt vollständige Pfade zurück. Verwenden Sie glob() für den Musterabgleich und scandir(), wenn Sie jeden Eintrag und volle Kontrolle über die Filterung möchten.

Fehlerbehandlung

Die Funktion scandir kann fehlschlagen, wenn der angegebene Verzeichnispfad ungültig ist oder das Verzeichnis nicht die erforderlichen Berechtigungen hat. Bei einem Fehler gibt sie false zurück und löst eine Warnung aus. Sie wirft keine Ausnahmen, daher sollten Sie den Rückgabewert direkt prüfen. Hier ein Beispiel:

Beispiel der Funktion scandir() in PHP mit Fehlerbehandlung

<?php

$dir = "/path/to/directory";
$files = scandir($dir);

if ($files === false) {
    echo "Error: Could not read the directory.";
} else {
    foreach ($files as $file) {
        echo $file . "<br>";
    }
}

Dieser Code prüft den Rückgabewert von scandir() und zeigt eine Fehlermeldung an, wenn das Verzeichnis nicht gelesen werden kann. Da scandir() bei einem Fehler eine Warnung (keine Ausnahme) auslöst, ist die strikte Prüfung === false der eigentliche Schutz Ihres Codes — das Unterdrücken der Warnung mit @scandir() wird nicht empfohlen, da Sie dabei die Diagnosemeldung verlieren.

Um die Warnung vollständig zu vermeiden, prüfen Sie zunächst, ob der Pfad ein lesbares Verzeichnis ist, bevor Sie scandir() aufrufen:

<?php

$dir = "/path/to/directory";

if (is_dir($dir)) {
    $files = scandir($dir);

    foreach (array_diff($files, ['.', '..']) as $file) {
        echo $file . "<br>";
    }
} else {
    echo "Error: '$dir' is not a valid directory.";
}

scandir() vs. andere Verzeichnisfunktionen

Einen Überblick über das breitere Werkzeugset finden Sie unter Arbeiten mit Verzeichnissen in PHP.

Fazit

Die Funktion scandir() ist eine bequeme Einzeilen-Methode zum Auslesen des Inhalts eines Verzeichnisses in PHP. Sie haben gelernt, wie Sie Einträge auflisten, sie mit den drei SCANDIR_SORT_*-Konstanten sortieren, nur Dateien oder nur Verzeichnisse behalten, nach Erweiterung filtern und Fehler sicher behandeln. Greifen Sie auf scandir() zurück, wenn Sie die vollständige Auflistung und volle Kontrolle möchten; greifen Sie auf glob() zurück, wenn ein einfacher Musterabgleich ausreicht.

Übungen