rewinddir()

Quando leggi una directory in PHP, un puntatore interno tiene traccia di quanto hai letto. Una volta raggiunta la fine, quel puntatore rimane lì — chiama di nuovo readdir() e ottieni false senza alcuna voce. rewinddir() riporta il puntatore alla prima voce in modo che tu possa leggere la directory una seconda volta senza riaprirla. Questa pagina illustra cosa fa la funzione, la sua sintassi, un esempio funzionante con più passaggi, le insidie comuni e quando usarla (e quando no).

Sintassi

rewinddir(?resource $dir_handle = null): void

• $dir_handle — un handle di directory precedentemente restituito da opendir(). Se omesso, PHP utilizza l'handle della chiamata più recente a opendir().
• Valore restituito — rewinddir() restituisce void (nelle versioni più vecchie di PHP, null). Non segnala successo o fallimento; se si passa un handle non valido, PHP genera un TypeError o un avviso.

È quasi sempre abbinata a opendir(), readdir() e closedir().

Come funziona rewinddir()

Un handle di directory si comporta come un cursore sulle voci della directory. readdir() avanza quel cursore di una voce per chiamata e restituisce false quando esaurisce le voci. rewinddir() riposiziona semplicemente il cursore all'inizio, così la successiva readdir() riparte dalla prima voce.

Leggere una directory due volte

Questo è il caso d'uso canonico: elencare una directory e poi elencarla di nuovo dallo stesso handle. Nota come readdir($h) non restituisce voci al secondo passaggio finché non viene chiamata rewinddir().

<?php
$h = opendir(__DIR__);
if ($h === false) {
    die("Failed to open directory\n");
}

echo "First pass:\n";
while (($file = readdir($h)) !== false) {
    echo "  $file\n";
}

// Without rewinddir(), this loop would print nothing.
rewinddir($h);

echo "Second pass:\n";
while (($file = readdir($h)) !== false) {
    echo "  $file\n";
}

closedir($h);
?>

Entrambi i passaggi stampano lo stesso insieme di voci (incluse le pseudo-directory . e .. che readdir() restituisce sempre).

Un'insidia comune: il controllo rigoroso di false

Confronta sempre il risultato di readdir() con !== false, non solo con != o un test truthy. Una directory può legittimamente contenere una voce chiamata "0", che è falsy in PHP — un controllo non rigoroso interromperebbe il ciclo prematuramente, saltando silenziosamente dei file.

<?php
// Wrong: stops as soon as it hits a file named "0" (or an empty name)
while ($file = readdir($h)) { /* ... */ }

// Correct: only stops at the genuine end of the stream
while (($file = readdir($h)) !== false) { /* ... */ }
?>

Quando usare rewinddir() — e quando no

Usa rewinddir() quando hai bisogno di più di un passaggio sullo stesso handle aperto, ad esempio per calcolare un totale nel primo passaggio (contare file, sommare dimensioni) e agire su ogni voce nel secondo. È meno costoso che chiamare closedir() e poi opendir() di nuovo, perché evita di riaprire il descrittore di file sottostante.

Se hai bisogno delle voci una sola volta o le vuoi ordinate, preferisci scandir(), che restituisce l'intero elenco come array in una singola chiamata — senza puntatori da gestire. Per una panoramica di tutte le funzioni sulle directory, consulta il capitolo PHP Directory.

Conclusione

rewinddir() riporta il puntatore interno di uno stream di directory all'inizio, permettendoti di rileggere la directory senza il costo di chiudere e riaprire l'handle. Abbinata a opendir(), readdir() e closedir(), rende l'attraversamento multi-passaggio delle directory semplice ed efficiente. Usa invece scandir() quando tutto ciò di cui hai bisogno è un singolo elenco ordinato.

graph TD
    A[opendir] --> B[readdir]
    B --> C{More items?}
    C -->|Yes| B
    C -->|No| D[rewinddir]
    D --> B
    B --> E[closedir]

Pratica