stat()

Introducción

La función stat() devuelve un array con metadatos de bajo nivel sobre un archivo: su tamaño, permisos, propietario, inodo, número de enlaces y tres marcas de tiempo (acceso, modificación y cambio de inodo). Es el envoltorio PHP sobre la llamada al sistema stat() de C, por lo que te proporciona en una sola llamada la misma información que de otro modo tendrías que obtener con múltiples funciones separadas como filesize(), filemtime() y fileperms().

Este artículo cubre la sintaxis, el significado completo de cada valor que devuelve stat(), los problemas comunes (la caché de stat, los enlaces simbólicos y los índices de cadena frente a los numéricos) y ejemplos ejecutables.

Sintaxis

stat(string $filename): array|false

• $filename — la ruta al archivo del que quieres información.
• Valor de retorno — un array que describe el archivo, o false si hay un fallo (por ejemplo, el archivo no existe o no se puede leer). Como puede devolver false, comprueba siempre el resultado antes de acceder a sus índices.

stat() sigue los enlaces simbólicos e informa sobre el archivo destino. Si necesitas los metadatos del propio enlace, usa lstat(). Para obtener el stat de un archivo para el que ya tienes un identificador abierto, usa fstat().

Qué devuelve stat()

El array devuelto es inusual: cada valor aparece dos veces — una bajo un índice numérico y otra bajo una clave de cadena descriptiva. Así, $info[7] e $info['size'] tienen el mismo valor. Este doble indexado existe por compatibilidad con versiones anteriores; se prefieren las claves con nombre para un código más legible.

Algunas notas:

• mode combina el tipo de archivo y los bits de permisos. Para obtener solo los bits de permisos Unix (como 0644), aplica la máscara & 0777; para mostrarlos en octal, envuélvelos con decoct().
• ctime es el tiempo de cambio de inodo (cuando los permisos, la propiedad o los enlaces cambiaron por última vez) — no es la hora de creación del archivo. La mayoría de los sistemas de archivos Unix no almacenan una hora de creación.
• Los valores rdev, blksize y blocks no tienen significado en Windows.

Ejemplo: Leer los Metadatos de un Archivo

Este ejemplo crea un archivo temporal, obtiene su stat y muestra el tamaño, los permisos y la hora de modificación:

<?php

// Create a small file to inspect.
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "Hello, stat()!");

$info = stat($path);
if ($info === false) {
    echo "Could not stat the file.";
    exit;
}

echo "Size: {$info['size']} bytes\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";

unlink($path); // clean up

Salida (los permisos y la hora exactos dependen de tu sistema):

Size: 14 bytes
Permissions: 600
Modified: 2026-06-21 12:00:00

Protégete siempre contra false: pasar una ruta inexistente produce una advertencia y false, e indexar false de otro modo lanzaría un error.

Precaución: la Caché de Stat

Por rendimiento, PHP almacena en caché los resultados de stat() y las funciones de archivo relacionadas. Si un archivo cambia durante la misma ejecución del script y lo vuelves a analizar, puedes obtener datos obsoletos. Limpia la caché con clearstatcache() antes de volver a leer:

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "first");
echo stat($path)['size'], "\n"; // 5

file_put_contents($path, "much longer content");
clearstatcache(true, $path);    // refresh cached metadata
echo stat($path)['size'], "\n"; // 19

unlink($path);

stat() frente a las Funciones de Propósito Único

Si solo necesitas una pieza de información, las funciones dedicadas son más claras y ligeramente más eficientes:

• Tamaño de archivo → filesize()
• Tiempo de modificación → filemtime()
• Último tiempo de acceso → fileatime()
• Permisos → fileperms()
• Tipo de archivo → filetype()

Recurre a stat() cuando necesites varios de estos a la vez, ya que realiza una única llamada al sistema en lugar de muchas. Antes de analizar el stat, también puedes verificar que la ruta es un archivo real con is_file() o file_exists().

Conclusión

La función stat() te proporciona una instantánea completa de bajo nivel de los metadatos de un archivo en una sola llamada. Recuerda comprobar si hay un retorno false, usar las claves de array con nombre para mayor legibilidad, aplicar la máscara mode con & 0777 para los permisos y limpiar la caché de stat si vuelves a leer un archivo que cambió durante la ejecución del script. Cuando solo necesites un atributo, prefiere la función de propósito único correspondiente.

Práctica