fileatime()

Qué hace la función fileatime()

La función fileatime() es una función integrada de PHP que devuelve el último tiempo de acceso de un archivo — el momento en que su contenido fue leído por última vez. El valor se devuelve como un entero Unix timestamp (el número de segundos desde el 1 de enero de 1970, UTC), que normalmente se formatea con date() antes de mostrárselo al usuario.

Esta página cubre la sintaxis, el valor de retorno, un ejemplo ejecutable, en qué se diferencia el tiempo de acceso de los tiempos de modificación y cambio relacionados, y el problema del almacenamiento en caché que confunde a la mayoría de las personas.

Sintaxis

fileatime(string $filename): int|false

• $filename — la ruta al archivo que desea inspeccionar. Puede ser relativa (resuelta respecto al directorio de trabajo del script) o absoluta.
• Valor de retorno — un entero Unix timestamp en caso de éxito, o false en caso de fallo (por ejemplo, el archivo no existe o no tiene permiso para ejecutar stat sobre él). Como false es un valor PHP válido, compare siempre con !== false en lugar de una verificación de veracidad flexible.

Advertencia sobre los tiempos de acceso en Linux. En los sistemas Linux modernos, las opciones de montaje como noatime o relatime detienen deliberadamente la actualización del tiempo de acceso en cada lectura para ahorrar escrituras en disco. Si fileatime() no cambia después de leer un archivo, eso se debe a la configuración del sistema de archivos, no a un error en su código.

Cómo usar fileatime()

1. Llame a fileatime(), pasando la ruta del archivo que desea verificar.
2. Compruebe el resultado contra false antes de usarlo, para que un archivo inexistente no produzca una advertencia cuando lo pase a date().
3. Formatee el timestamp con date() para convertirlo en una cadena legible por humanos.

<?php

// Create a small file so the example is self-contained and runnable.
$filename = 'example.txt';
file_put_contents($filename, "Hello, fileatime!\n");

// Read it back to register an access.
$contents = file_get_contents($filename);

$lastAccess = fileatime($filename);

if ($lastAccess !== false) {
    $when = date('Y-m-d H:i:s', $lastAccess);
    echo "The file {$filename} was last accessed on {$when}.\n";
} else {
    echo "Could not read the access time for {$filename}.\n";
}

unlink($filename); // tidy up

Este script crea example.txt, lo lee y luego pregunta a fileatime() cuándo fue accedido por última vez. El control !== false significa que un archivo inexistente o ilegible se maneja correctamente en lugar de emitir una advertencia. La salida se ve así:

The file example.txt was last accessed on 2026-06-21 10:42:07.

fileatime() vs. filemtime() vs. filectime()

PHP expone tres timestamps estrechamente relacionados. Elegir el correcto es importante:

Si desea saber "cuándo alguien abrió este archivo por última vez", use fileatime(). Si desea saber "cuándo cambiaron los datos por última vez" (el caso común para la invalidación de caché), use filemtime().

El problema del almacenamiento en caché

PHP almacena en caché el resultado de las funciones de estado de archivo como fileatime(), filemtime() y stat() durante la duración de una solicitud. Si lee un archivo de nuevo y vuelve a comprobar su tiempo de acceso dentro de la misma ejecución del script, puede obtener un valor obsoleto. Limpie la caché con clearstatcache() antes de volver a leer:

<?php

$filename = 'example.txt';
file_put_contents($filename, "data\n");

$first = fileatime($filename);

clearstatcache();                       // force a fresh stat() next time
$contents = file_get_contents($filename);
clearstatcache();
$second = fileatime($filename);

echo ($second >= $first)
    ? "Access time is fresh.\n"
    : "Access time looks stale.\n";

unlink($filename);

¿Cuándo usaría esto?

• Auditar qué archivos se han leído recientemente (rotación de registros, limpieza de "los menos usados recientemente").
• Detectar cargas o archivos temporales no utilizados que se pueden eliminar de forma segura.
• Diagnosticar si un proceso está accediendo realmente a un archivo que se espera que toque.

Para la lógica basada en modificaciones (reconstruir una caché cuando cambian los datos de origen), use filemtime() en su lugar. Para verificar que un archivo existe antes de llamar a cualquiera de estas funciones, combínelas con file_exists(). Para el conjunto completo de metadatos en una sola llamada, consulte stat().

Resumen

fileatime() devuelve el Unix timestamp del último acceso de un archivo, o false en caso de fallo. Siempre proteja el resultado con !== false, formatéelo con date(), y recuerde dos problemas: los montajes de Linux pueden suprimir las actualizaciones del tiempo de acceso, y PHP almacena en caché los resultados de stat dentro de una solicitud a menos que llame a clearstatcache().

Práctica