dir()

Introducción

Este capítulo explica cómo trabajar con directorios en PHP: abrirlos, leerlos, crearlos y eliminarlos, además de la función dir() (ya eliminada) y sus reemplazos modernos. PHP incluye un conjunto completo de funciones integradas para estas tareas, de modo que puedes listar el contenido de una carpeta, recorrer un árbol de directorios o limpiar archivos sin invocar comandos del sistema operativo.

Las funciones de directorio son más útiles cuando se construye un gestor de subidas, se genera un listado de archivos para una página de descargas, se eliminan archivos temporales o se escanea en tiempo de ejecución una carpeta de plantillas o imágenes.

Funciones de Directorio en PHP

PHP agrupa el trabajo con directorios en un puñado de funciones procedurales, además de una clase orientada a objetos llamada DirectoryIterator. Las más comunes son:

• opendir() — abre un directorio y devuelve un manejador (un recurso del que se lee)
• readdir() — lee la siguiente entrada de un manejador de directorio abierto
• closedir() — cierra un manejador de directorio y libera el recurso
• scandir() — lee todas las entradas en un array con una sola llamada
• glob() — devuelve rutas que coinciden con un patrón de comodín de shell
• mkdir() — crea un nuevo directorio
• rmdir() — elimina un directorio vacío
• is_dir() — comprueba si una ruta es un directorio

Cualquier listado de directorio en PHP incluye las entradas especiales . (el directorio en sí) y .. (su directorio padre). Casi siempre conviene omitirlas: olvidarlo es una fuente habitual de errores.

Usar opendir() y readdir() para Leer un Directorio

opendir() abre un directorio y devuelve un manejador de directorio. Luego se pasa ese manejador a readdir(), que devuelve el nombre de la siguiente entrada cada vez que se llama, y false cuando no hay más entradas. Cierra siempre el manejador con closedir() cuando hayas terminado.

Como readdir() puede devolver legítimamente "0" (un archivo cuyo nombre es literalmente 0), compara su resultado con !== false en lugar de una comprobación laxa, para que un nombre de archivo con valor falso no se confunda con el final de la lista.

Ejemplo de opendir() y readdir() en PHP

<?php

$dir = "/path/to/directory";
if (is_dir($dir)) {
    if ($dh = opendir($dir)) {
        while (($file = readdir($dh)) !== false) {
            if ($file === "." || $file === "..") {
                continue; // skip self and parent
            }
            echo "filename: " . $file . PHP_EOL;
        }
        closedir($dh);
    }
}

Para un directorio que contiene a.txt, b.log y report.csv, esto imprime:

filename: b.log
filename: report.csv
filename: a.txt

El orden no es alfabético: readdir() devuelve las entradas en el orden en que las almacena el sistema de archivos. Si necesitas un orden predecible, usa scandir() (que ordena) o clasifica los resultados tú mismo.

Usar scandir() para Listar un Directorio de una Sola Vez

scandir() lee el contenido completo de un directorio en un array con una sola llamada y, a diferencia de readdir(), ordena el resultado alfabéticamente por defecto. Es la forma más cómoda de obtener una lista ordenada de archivos. Sigue incluyendo . y .., así que fíltralos cuando solo quieras archivos reales.

Uso de la Función scandir() en PHP

<?php

$dir = "/path/to/directory";
$files = scandir($dir);
print_r($files);

Para un directorio que contiene a.txt, b.log y report.csv, la salida es:

Array
(
    [0] => .
    [1] => ..
    [2] => a.txt
    [3] => b.log
    [4] => report.csv
)

Pasa SCANDIR_SORT_DESCENDING como tercer argumento para invertir el orden, o SCANDIR_SORT_NONE para omitir la ordenación (lo que es más rápido en directorios muy grandes).

Buscar Archivos con glob()

Cuando solo quieres archivos que coincidan con un patrón —todos los archivos .txt, o todo lo que empiece por report— glob() es la opción más limpia. Acepta un patrón de comodín de shell y devuelve un array con las rutas coincidentes:

<?php

foreach (glob("/path/to/directory/*.txt") as $file) {
    echo $file . PHP_EOL;
}

Si en nuestro directorio de ejemplo solo a.txt coincide, esto imprime:

/path/to/directory/a.txt

A diferencia de scandir(), glob() no incluye . ni .., y devuelve rutas completas en lugar de solo nombres de archivo.

Crear Directorios con mkdir()

La función mkdir() crea un nuevo directorio. Su primer argumento es la ruta, el segundo establece los permisos (un valor octal como 0755), y el tercer argumento opcional, cuando es true, crea de forma recursiva los directorios padre que falten.

Uso de la Función mkdir() en PHP

mkdir("/path/to/my/new/directory", 0755, true);

Sin el indicador true, mkdir() falla con un aviso si algún directorio padre no existe aún. En sistemas tipo Unix, los permisos reales también se ven afectados por la umask del proceso.

Eliminar Directorios con rmdir()

La función rmdir() elimina un directorio. Recibe la ruta del directorio que deseas eliminar.

Uso de la Función rmdir() en PHP

rmdir("/path/to/my/new/directory");

Nota: rmdir() solo elimina directorios vacíos. Para eliminar un directorio que aún contiene archivos, elimina primero los archivos (y cualquier subdirectorio), por ejemplo iterando el contenido con scandir() y llamando a unlink() en cada archivo.

El Reemplazo Moderno: DirectoryIterator

Para código orientado a objetos, la clase DirectoryIterator de SPL es la forma recomendada de recorrer un directorio. Es iterable con foreach y proporciona información detallada sobre cada entrada —nombre, tamaño, tipo y tiempo de modificación— sin llamadas a funciones adicionales:

<?php

foreach (new DirectoryIterator("/path/to/directory") as $entry) {
    if ($entry->isDot()) {
        continue; // skip "." and ".."
    }
    echo $entry->getFilename() . PHP_EOL;
}

Para un directorio que contiene a.txt, b.log y report.csv, esto imprime:

b.log
report.csv
a.txt

isDot() omite cómodamente tanto . como .. en una sola comprobación. Para recorrer un árbol de directorios completo, incluyendo subcarpetas, usa RecursiveDirectoryIterator junto con RecursiveIteratorIterator.

La Función Legacy dir()

Obsoleta: La función dir() fue declarada obsoleta en PHP 7.4 y eliminada en PHP 8.0. Usa DirectoryIterator o scandir() en su lugar. El ejemplo a continuación se proporciona únicamente para el mantenimiento de código más antiguo.

La función dir() devuelve un objeto Directory que ofrece una forma orientada a objetos de leer el contenido de un directorio. A diferencia de scandir(), que devuelve un array simple, dir() devuelve un objeto con métodos como read(), rewind() y close(). Ten en cuenta que dir() no es un alias de scandir() —sirven para propósitos distintos y devuelven tipos de datos diferentes.

Uso de la Función dir() en PHP (legacy)

<?php
$dir = dir("/path/to/directory");
while (($file = $dir->read()) !== false) {
    echo "filename: " . $file . PHP_EOL;
}
$dir->close();

Conclusión

PHP ofrece varias formas de trabajar con directorios. Usa scandir() o glob() para listados rápidos y ordenados, el trío opendir()/readdir()/closedir() cuando quieras procesar entradas de una en una, y DirectoryIterator para un recorrido orientado a objetos limpio. Crea y elimina carpetas con mkdir() y rmdir(), y recurre a RecursiveDirectoryIterator cuando necesites descender en subdirectorios. Para una visión más amplia del trabajo con el sistema de archivos, consulta los capítulos PHP Directory y PHP Filesystem.

Práctica