filemtime()

La función filemtime() es una función integrada de PHP que devuelve la hora en que el contenido de un archivo fue modificado por última vez, como una marca de tiempo Unix. Es una de las funciones de inspección del sistema de archivos de PHP y se usa habitualmente para la invalidación de caché, etiquetas de "última actualización" y para detectar si un archivo ha cambiado desde la última lectura.

Este capítulo cubre la sintaxis, el valor de retorno, la diferencia entre filemtime() y las funciones relacionadas filectime() / fileatime(), el formateo del resultado para los usuarios, el manejo de errores y el problema del almacenamiento en caché de resultados que confunde a casi todo el mundo.

Sintaxis

filemtime(string $filename): int|false

• $filename — ruta al archivo (o directorio) a inspeccionar.
• Valor de retorno — la hora de modificación como marca de tiempo Unix (segundos desde el 1 de enero de 1970 UTC) si tiene éxito, o false si falla.

El "tiempo de modificación" (mtime) cambia siempre que el contenido del archivo se escribe. No cambia cuando el archivo simplemente se lee, ni cuando solo cambian sus metadatos (permisos, propietario); eso es el tiempo de cambio de inodo, que reporta filectime().

Un ejemplo básico

Dado que una marca de tiempo Unix es simplemente un número entero grande, normalmente se pasa a date() para producir una cadena legible:

<?php

$filename = __FILE__; // inspect this script itself

$timestamp = filemtime($filename);
$readable  = date('F d Y H:i:s', $timestamp);

echo "The file was last modified on $readable";

__FILE__ es una constante mágica que siempre apunta al script actual, por lo que este fragmento se ejecuta sin necesidad de crear un archivo separado. filemtime() devuelve la marca de tiempo y date() la formatea (aquí: nombre completo del mes, día, año y luego hora en formato de 24 horas).

Siempre gestiona los errores

filemtime() devuelve false cuando el archivo no existe o no se puede leer, y además emite una advertencia. Como false es aproximadamente igual a 0, nunca pases el resultado sin procesar directamente a date() — compruébalo primero, idealmente después de confirmar que el archivo existe con file_exists():

<?php

$filename = 'does-not-exist.txt';

if (!file_exists($filename)) {
    echo "File not found.";
} else {
    $timestamp = filemtime($filename);

    if ($timestamp === false) {
        echo "Could not read the modification time.";
    } else {
        echo "Last modified: " . date('Y-m-d H:i:s', $timestamp);
    }
}

Usa la comparación estricta === false: una marca de tiempo legítima nunca es false, pero == false también capturaría la marca de tiempo 0 (imposible en la práctica).

mtime vs. ctime vs. atime

PHP expone tres marcas de tiempo de archivo diferentes. Saber cuál usar evita errores sutiles:

Para mostrar cuándo fue editado por última vez un archivo, casi siempre querrás filemtime().

El problema del caché: clearstatcache()

PHP almacena en caché los resultados de las funciones del sistema de archivos como filemtime() durante la duración de una solicitud. Si cambias un archivo y luego llamas a filemtime() de nuevo en el mismo script, puede que obtengas el valor obsoleto. Llama a clearstatcache() para forzar una consulta actualizada:

<?php

$filename = tempnam(sys_get_temp_dir(), 'demo');

file_put_contents($filename, 'first write');
$first = filemtime($filename);

sleep(1);
touch($filename);          // bump the mtime

clearstatcache();          // without this, you may still see $first
$second = filemtime($filename);

echo $second > $first ? "mtime updated\n" : "mtime unchanged (cached)\n";

unlink($filename);

Aquí touch() actualiza el tiempo de modificación, y clearstatcache() garantiza que el segundo filemtime() lo refleje.

Un uso práctico: cache busting

Un uso habitual en el mundo real es añadir el mtime del archivo a la URL de un recurso para que los navegadores lo vuelvan a descargar solo cuando el archivo cambia realmente:

<?php

$cssPath = __FILE__; // pretend this is 'styles.css'
$version = filemtime($cssPath);

echo "/assets/styles.css?v=$version";

Cada vez que se edita el CSS, $version cambia, invalidando automáticamente la caché del navegador.

Conclusión

filemtime() informa cuándo fue modificado por última vez el contenido de un archivo, como una marca de tiempo Unix, y devuelve false en caso de error. Combínala con date() para formatear el resultado, protégete contra false, recuerda clearstatcache() cuando vuelvas a leer un archivo que acabas de cambiar, y recurre a filectime() o fileatime() cuando necesites el tiempo de cambio o acceso. Para un conjunto completo de estadísticas de archivo en una sola llamada, consulta stat().

Práctica