readdir()

La función readdir() de PHP lee una entrada a la vez de un directorio que ya has abierto con opendir(). Cada llamada devuelve el nombre del siguiente archivo o subdirectorio y avanza un puntero interno, por lo que llamarla en un bucle te permite recorrer todos los elementos de una carpeta. Esta página explica la sintaxis, el valor de retorno, el patrón de bucle que evita un error común, y cómo readdir() se compara con alternativas de mayor nivel.

Sintaxis

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

• $dir_handle — un identificador de directorio devuelto por opendir(). Si se omite, PHP usa el último identificador abierto por opendir().
• Valor de retorno — el nombre de archivo de la siguiente entrada como string, o false cuando no hay más entradas. Las entradas incluyen los nombres especiales . (directorio actual) y .. (directorio padre), y se devuelven en el orden en que el sistema de archivos las almacena, no ordenadas.

Leer un directorio

Para usar readdir(), primero abre un identificador de directorio con opendir(), haz un bucle con readdir() hasta que devuelva false, luego libera el identificador 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);
}

Esto abre el directorio, itera por su contenido e imprime cada nombre excepto . y ... La llamada a closedir() libera el identificador cuando hayas terminado.

Por qué usar false !== y no solo una comprobación de verdad

La comparación estricta false !== ($entry = readdir($handle)) es esencial, no estilística. Un directorio puede contener legítimamente una entrada llamada "0", y una comprobación de cadena vacía también fallaría. PHP trata la cadena "0" como falsa, por lo que escribir while ($entry = readdir($handle)) detendría el bucle anticipadamente al llegar a dicho archivo. Comparar estrictamente contra false hace que el bucle termine solo cuando readdir() realmente se queda sin entradas.

Filtrar entradas por extensión

readdir() devuelve nombres sin procesar, por lo que cualquier filtrado depende de ti. Combínalo con pathinfo() para conservar solo los tipos de archivo que te interesan — aquí, imágenes:

<?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) extrae la extensión de cada nombre, e in_array(..., true) (modo estricto) la comprueba contra la lista de permitidos para que solo se impriman los archivos coincidentes.

Releer el mismo directorio

Como cada llamada a readdir() avanza el puntero interno, un segundo bucle sobre el mismo identificador no devuelve nada — el puntero ya está al final. Usa rewinddir() para restablecerlo a la primera entrada sin reabrir el directorio:

<?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() es el bloque de construcción de bajo nivel. En la mayoría del código moderno se recurre a una alternativa de una sola llamada:

• scandir() devuelve todas las entradas como un array ordenado en una sola llamada — sin la burocracia de opendir/closedir.
• glob() hace coincidir un patrón estilo shell (por ejemplo *.png) y devuelve rutas completas, lo que convierte el filtrado por extensión en una sola línea.

Recurre a readdir() cuando quieras procesar entradas una a una sin cargar todo el listado en memoria (útil para directorios muy grandes), o cuando necesites un control detallado sobre la iteración.

Errores comunes

• Siempre omite . y .. — readdir() los incluye, y olvidar filtrarlos es el error más frecuente, especialmente en recorridos recursivos de directorios.
• opendir() puede fallar. Si la ruta no existe o no es legible devuelve false y emite una advertencia, por eso los ejemplos protegen el bucle con if ($handle = opendir($dir)).
• Cierra tus identificadores. Llama a closedir() (o deja que el script termine) para liberar el recurso.
• El orden no está garantizado. Si necesitas salida ordenada, usa scandir() u ordena los nombres tú mismo.

Práctica