eio_readdir — Funktion · PHP-Referenz

Signatur

eio_readdir(string $path, int $flags, int $pri, callable $callback, mixed $data = null): resource|false

Beschreibung

eio_readdir() gehört zur eio-Erweiterung, die asynchrone I/O-Operationen auf Basis der libeio-Bibliothek bereitstellt. Die Funktion liest alle Einträge eines Verzeichnisses, ohne den Prozess zu blockieren, und ruft nach Abschluss den angegebenen $callback mit den Ergebnissen auf.

Über den Parameter $flags lässt sich steuern, welche Zusatzinformationen zurückgegeben werden. Mit EIO_READDIR_DENTS erhält man ein assoziatives Array mit Name, Typ und Inode-Nummer jedes Eintrags; mit EIO_READDIR_DIRS_FIRST werden Unterverzeichnisse an den Anfang gestellt; EIO_READDIR_STAT_ORDER sortiert Einträge so, dass nachfolgende stat()-Aufrufe effizienter werden. Die Flags lassen sich per bitweisem OR kombinieren.

Der Callback wird mit den Argumenten ($data, $result) aufgerufen, wobei $result je nach gesetzten Flags entweder ein einfaches Array von Dateinamen oder ein assoziatives Array mit detaillierten Einträgen ist. Die Funktion eignet sich besonders in ereignisgesteuerten Anwendungen (z. B. mit libevent oder ev), bei denen blockierende Dateisystemoperationen vermieden werden sollen.

Damit eio funktioniert, muss die eio-Erweiterung geladen und eine Ereignisschleife integriert sein, die eio_event_loop() oder eine äquivalente Polling-Methode regelmäßig aufruft.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Pfad zum Verzeichnis, das gelesen werden soll.
$flags Pflicht	int		Bitmask aus `EIO_READDIR_*`-Konstanten. Steuert, welche Zusatzinformationen im Ergebnis enthalten sind. `0` liefert nur einfache Dateinamen.
$pri Pflicht	int		Priorität der Anfrage. Erlaubte Werte: `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX`.
$callback Pflicht	callable		Callback-Funktion mit der Signatur `function(mixed $data, mixed $result): void`. `$result` enthält die Verzeichniseinträge; bei einem Fehler ist `$result` `false`.
$data	mixed	null	Beliebige benutzerdefinierte Daten, die unverändert als erstes Argument an den Callback übergeben werden.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt eine eio-Anfrage-Ressource zurück, mit der die Operation über eio_cancel() abgebrochen werden kann, oder false bei einem Fehler.

Beispiele

Einfaches Auflisten eines Verzeichnisses

<?php
// eio-Erweiterung muss geladen sein

eio_readdir(
    '/var/www',
    0,
    EIO_PRI_DEFAULT,
    function ($data, $result) {
        if ($result === false) {
            echo "Fehler beim Lesen des Verzeichnisses.\n";
            return;
        }
        // $result ist ein Array mit Dateinamen
        foreach ($result['names'] as $name) {
            echo $name . "\n";
        }
    },
    null
);

eio_event_loop();

index.php config.ini public vendor

Verzeichnis mit DENTS-Flag für detaillierte Einträge

<?php
// EIO_READDIR_DENTS liefert Name, Typ und Inode-Nummer

eio_readdir(
    '/tmp',
    EIO_READDIR_DENTS | EIO_READDIR_DIRS_FIRST,
    EIO_PRI_DEFAULT,
    function ($data, $result) {
        if ($result === false) {
            echo "Lesefehler.\n";
            return;
        }
        foreach ($result['dents'] as $entry) {
            printf(
                "Name: %-30s Typ: %d Inode: %d\n",
                $entry['name'],
                $entry['type'],
                $entry['inode']
            );
        }
    },
    'mein-kontext'
);

eio_event_loop();

Name: mydir Typ: 4 Inode: 131073 Name: tempfile.txt Typ: 8 Inode: 131074

// Wichtig · Fallstricke

Voraussetzung: Die eio-Erweiterung ist nicht standardmäßig in PHP enthalten und muss separat über PECL installiert werden (pecl install eio). Sie ist primär für Linux ausgelegt; auf Windows ist die Unterstützung eingeschränkt.

Ereignisschleife: eio_readdir() ist nicht-blockierend – der Callback wird erst ausgeführt, wenn eio_event_loop() oder ein kompatibler Ereignis-Loop (z. B. aus der event- oder ev-Erweiterung) die ausstehenden Anfragen verarbeitet. Ohne eine solche Schleife wird der Callback niemals aufgerufen.

Pfadsicherheit: Nutzereingaben, die als $path verwendet werden, müssen vorher validiert und bereinigt werden, um Path-Traversal-Angriffe (../) zu vermeiden.

Siehe auch

eio_event_loop eio_cancel eio_stat eio_open scandir opendir