readdir()

La funzione PHP readdir() legge una voce alla volta da una directory già aperta con opendir(). Ogni chiamata restituisce il nome del file o della sottodirectory successiva e avanza un puntatore interno, quindi chiamarla in un ciclo consente di scorrere tutti gli elementi di una cartella. Questa pagina illustra la sintassi, il valore restituito, il pattern di ciclo che evita un bug comune e come readdir() si confronta con le alternative di livello superiore.

Sintassi

readdir(resource $dir_handle = null): string|false

• $dir_handle — un handle di directory restituito da opendir(). Se omesso, PHP utilizza l'ultimo handle aperto da opendir().
• Valore restituito — il nome file della voce successiva come string, oppure false quando non ci sono più voci. Le voci includono i nomi speciali . (directory corrente) e .. (directory padre), e vengono restituite nell'ordine in cui il filesystem le memorizza, non ordinate.

Lettura di una directory

Per utilizzare readdir(), aprire prima un handle di directory con opendir(), eseguire il ciclo con readdir() fino a quando non restituisce false, quindi rilasciare l'handle con closedir():

<?php

$dir = __DIR__; // the directory this script lives in

if ($handle = opendir($dir)) {
    while (false !== ($entry = readdir($handle))) {
        if ($entry !== "." && $entry !== "..") {
            echo "$entry\n";
        }
    }
    closedir($handle);
}

Questo apre la directory, itera attraverso il suo contenuto e stampa ogni nome eccetto . e ... La chiamata a closedir() libera l'handle al termine.

Perché false !== e non un semplice controllo truthy

Il confronto rigoroso false !== ($entry = readdir($handle)) è essenziale, non stilistico. Una directory può legittimamente contenere una voce di nome "0", e un controllo su stringa vuota si comporterebbe altrettanto male. PHP tratta la string "0" come falsy, quindi scrivere while ($entry = readdir($handle)) interromperebbe il ciclo anticipatamente nel momento in cui incontrasse tale file. Confrontando in modo rigoroso contro false il ciclo termina solo quando readdir() esaurisce effettivamente le voci.

Filtraggio delle voci per estensione

readdir() restituisce nomi grezzi, quindi qualsiasi filtraggio spetta a te. Combinala con pathinfo() per conservare solo i tipi di file che interessano — in questo caso, le immagini:

<?php

$dir = __DIR__;
$allowed = ['jpg', 'jpeg', 'png', 'gif'];

if ($handle = opendir($dir)) {
    while (false !== ($entry = readdir($handle))) {
        $extension = strtolower(pathinfo($entry, PATHINFO_EXTENSION));
        if ($entry !== "." && $entry !== ".." && in_array($extension, $allowed, true)) {
            echo "$entry\n";
        }
    }
    closedir($handle);
}

pathinfo($entry, PATHINFO_EXTENSION) estrae l'estensione da ogni nome, e in_array(..., true) (modalità strict) la confronta con la lista consentita in modo che vengano stampati solo i file corrispondenti.

Rilettura della stessa directory

Poiché ogni chiamata a readdir() avanza il puntatore interno, un secondo ciclo sullo stesso handle non restituisce nulla — il puntatore è già alla fine. Usa rewinddir() per riportarlo alla prima voce senza riaprire la directory:

<?php

$handle = opendir(__DIR__);

while (false !== ($entry = readdir($handle))) { /* first pass */ }

rewinddir($handle); // back to the start

while (false !== ($entry = readdir($handle))) {
    // second pass sees every entry again
}

closedir($handle);

readdir() vs scandir() vs glob()

readdir() è il blocco fondamentale di basso livello. Nel codice moderno si preferisce di solito un'alternativa in una sola chiamata:

• scandir() restituisce tutte le voci come array ordinato in un'unica chiamata — senza la gestione di opendir/closedir.
• glob() abbina un pattern in stile shell (ad esempio *.png) e restituisce percorsi completi, rendendo il filtraggio per estensione una riga sola.

Ricorrere a readdir() è indicato quando si vuole elaborare le voci una alla volta senza caricare in memoria l'intero elenco (utile per directory molto grandi), oppure quando si ha bisogno di un controllo dettagliato sull'iterazione.

Errori comuni

• Salta sempre . e .. — readdir() le include, e dimenticare di filtrarle è il bug più frequente, specialmente nelle scansioni ricorsive.
• opendir() può fallire. Se il percorso non esiste o non è leggibile restituisce false ed emette un avviso, ecco perché negli esempi il ciclo è protetto con if ($handle = opendir($dir)).
• Chiudi gli handle. Chiama closedir() (o lascia terminare lo script) per rilasciare la risorsa.
• L'ordine non è garantito. Se hai bisogno di output ordinato, usa scandir() oppure ordina i nomi da solo.

Esercizio