lstat()

¿Qué es la función lstat()?

lstat() recopila estadísticas (tamaño, marcas de tiempo, propietario, permisos y más) sobre un archivo indicado por $filename. La "l" corresponde a link (enlace): a diferencia de stat(), que sigue un enlace simbólico e informa sobre el destino al que apunta, lstat() informa sobre el enlace en sí mismo.

Esta distinción solo importa para los enlaces simbólicos. Cuando $filename es un archivo ordinario, lstat() y stat() devuelven datos idénticos.

Esta página cubre la sintaxis, el array que devuelve, un ejemplo ejecutable que lo contrasta con stat(), y los errores comunes que hay que vigilar.

Sintaxis

lstat(string $filename): array|false

• $filename — ruta al archivo o enlace simbólico a inspeccionar.
• Devuelve un array asociativo de estadísticas en caso de éxito, o false en caso de fallo (por ejemplo, si la ruta no existe).

Un Ejemplo Ejecutable

El siguiente script crea un archivo real y un enlace simbólico que apunta a él, luego inspecciona ambos con lstat() y stat() para que puedas ver la diferencia:

<?php

$target = sys_get_temp_dir() . '/lstat_target.txt';
$link   = sys_get_temp_dir() . '/lstat_link';

file_put_contents($target, 'hello');   // 5-byte target file
@unlink($link);
symlink($target, $link);

$linkInfo   = lstat($link);   // the link itself
$targetInfo = stat($link);    // follows the link to the target

echo "Link size (lstat):  {$linkInfo['size']} bytes\n";
echo "Target size (stat): {$targetInfo['size']} bytes\n";
echo "Link modified:      " . date('Y-m-d', $linkInfo['mtime']) . "\n";

unlink($link);
unlink($target);

Salida típica:

Link size (lstat):  65 bytes
Target size (stat): 5 bytes
Link modified:      2026-06-20

El tamaño devuelto por lstat() es la longitud de los datos de la ruta del enlace simbólico, no el tamaño del archivo al que apunta — esa es exactamente la información que stat() te ocultaría.

El Array Devuelto

lstat() devuelve la misma estructura que stat(): un array de 26 elementos donde cada valor aparece dos veces — una vez bajo un índice numérico y otra bajo una clave de cadena legible. Usa siempre las claves con nombre para mayor claridad:

Como las claves con nombre y las numéricas contienen los mismos valores, $info['size'] y $info[7] son intercambiables — pero la forma con nombre es mucho más fácil de leer.

Cuándo usar lstat() vs stat()

• Usa stat() cuando te interesa el contenido del archivo y quieres que los enlaces se resuelvan de forma transparente.
• Usa lstat() cuando estés auditando el sistema de archivos en sí — por ejemplo, para distinguir archivos reales de enlaces simbólicos, o para detectar un enlace roto cuyo destino fue eliminado.

Para comprobar si una ruta es un enlace simbólico antes de llamar a lstat(), combínalo con is_link(). Para leer a dónde apunta un enlace, usa readlink(), y para crear uno, usa symlink().

Consideraciones Importantes

• Caché de estadísticas obsoleta. PHP almacena en caché los resultados de stat/lstat por solicitud. Si un archivo cambia durante la ejecución, llama a clearstatcache(true, $filename) antes de volver a leerlo.
• Windows. Los enlaces simbólicos existen en Windows pero requieren privilegios elevados para crearlos; el comportamiento puede diferir de los sistemas POSIX.
• Permisos. Tu proceso PHP necesita acceso de lectura al directorio que contiene el enlace. En sistemas reforzados, los módulos de seguridad (como SELinux o las restricciones de open_basedir) pueden bloquear el acceso incluso cuando los permisos del archivo parecen correctos.

Conclusión

lstat() te proporciona los metadatos de un enlace simbólico sin seguirlo — lo único que stat() no puede hacer. Úsalo siempre que necesites inspeccionar los enlaces en sí en lugar de sus destinos, lee los valores por sus claves con nombre, y comprueba siempre si el retorno es false antes de confiar en el resultado.

Práctica