rewinddir()

Cuando lees un directorio en PHP, un puntero interno registra hasta dónde has llegado. Una vez que alcanzas el final, ese puntero permanece ahí — llama a readdir() de nuevo y obtienes false sin más entradas. rewinddir() mueve el puntero de vuelta a la primera entrada para que puedas leer el directorio una segunda vez sin reabrirlo. Esta página explica qué hace la función, su sintaxis, un ejemplo funcional de múltiples pasadas, errores comunes y cuándo (y cuándo no) usarla.

Sintaxis

rewinddir(?resource $dir_handle = null): void

• $dir_handle — un recurso de directorio devuelto previamente por opendir(). Si se omite, PHP usa el recurso de la llamada más reciente a opendir().
• Valor de retorno — rewinddir() devuelve void (en versiones antiguas de PHP, null). No indica éxito o fracaso; si pasas un recurso inválido, PHP lanza un TypeError o una advertencia.

Casi siempre se usa junto con opendir(), readdir() y closedir().

Cómo funciona rewinddir()

Un recurso de directorio se comporta como un cursor sobre las entradas del directorio. readdir() avanza ese cursor una entrada por llamada y devuelve false cuando se agota. rewinddir() simplemente reposiciona el cursor al principio para que el siguiente readdir() empiece desde la primera entrada.

Leer un directorio dos veces

Este es el caso de uso canónico: listar un directorio y luego listarlo de nuevo desde el mismo recurso. Observa cómo readdir($h) no devuelve entradas en la segunda pasada hasta que se llama a 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);
?>

Ambas pasadas imprimen el mismo conjunto de entradas (incluidos los pseudodirectorios . y .. que readdir() siempre devuelve).

Un error común: la comparación estricta con false

Compara siempre el resultado de readdir() con !== false, no con != ni una prueba de veracidad. Un directorio puede contener legítimamente una entrada llamada "0", que es falsy en PHP — una comparación laxa detendría el bucle antes de tiempo y omitiría archivos silenciosamente.

<?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) { /* ... */ }
?>

Cuándo usar rewinddir() — y cuándo no

Usa rewinddir() cuando necesitas más de una pasada sobre el mismo recurso abierto, por ejemplo para calcular un total en la primera pasada (contar archivos, sumar tamaños) y actuar sobre cada entrada en la segunda. Es más eficiente que llamar a closedir() y opendir() de nuevo porque evita reabrir el descriptor de archivo subyacente.

Si solo necesitas las entradas una vez, o las quieres ordenadas, prefiere scandir(), que devuelve toda la lista como un array en una sola llamada — sin puntero que gestionar. Para una visión general de todas las funciones de directorio, consulta el capítulo PHP Directory.

Conclusión

rewinddir() restablece el puntero interno de un flujo de directorio al inicio, permitiéndote releer el directorio sin la sobrecarga de cerrar y reabrir el recurso. Combinada con opendir(), readdir() y closedir(), hace que el recorrido de directorios en múltiples pasadas sea simple y eficiente. Recurre a scandir() cuando solo necesites un listado ordenado en una única llamada.

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

Práctica