filectime()

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

La función filectime() es una función integrada de PHP que devuelve el tiempo de cambio de inodo de un archivo: una marca de tiempo Unix (el número de segundos transcurridos desde el 1 de enero de 1970) que representa el momento en que los metadatos del archivo cambiaron por última vez. El "inodo" es la estructura de datos que utiliza un sistema de archivos tipo Unix para almacenar información sobre un archivo (sus permisos, propietario, tamaño y la ubicación de sus bloques de datos) de forma independiente al contenido real del archivo.

Un punto de confusión frecuente: filectime() no devuelve el tiempo de creación del archivo. La "c" significa change (cambio), no create (creación). El tiempo de cambio de inodo se actualiza cada vez que los metadatos del archivo cambian, por ejemplo al ejecutar chmod, chown, al renombrar el archivo, o incluso al editar su contenido (lo que también actualiza los metadatos). PHP no dispone de una función portátil para obtener el tiempo de creación real.

Utiliza la función correcta según lo que necesitas:

• filectime() — cuándo cambió por última vez el inodo (metadatos) (permisos, propietario, conteo de enlaces, renombrado).
• filemtime() — cuándo se modificó por última vez el contenido del archivo.
• fileatime() — cuándo se accedió por última vez al archivo (lectura).

Esta es la sintaxis básica de la función filectime():

La sintaxis PHP de filectime()

filectime(string $filename): int|false

Donde $filename es la ruta del archivo a comprobar. La función devuelve el tiempo de cambio de inodo como una marca de tiempo Unix, o false (junto con un E_WARNING) si el archivo no existe o no se puede acceder a él. Dado que false y una marca de tiempo pueden parecer "falsy" en comparaciones no estrictas (una marca de tiempo nunca es 0 en la práctica, pero el código defensivo importa), comprueba siempre el resultado con el operador estricto !== false.

¿Cómo usar la función filectime()?

Usar la función filectime() es sencillo. Estos son los pasos a seguir:

1. Llama a la función filectime() pasando el nombre del archivo que deseas comprobar.
2. La función devolverá una marca de tiempo Unix que representa el tiempo de cambio de inodo, o false si falla.
3. Puedes formatear la marca de tiempo Unix usando la función date() para mostrar la hora en un formato más legible para los humanos.

A continuación se muestra un fragmento de código de ejemplo que demuestra cómo usar la función filectime():

¿Cómo usar la función filectime()?

<?php

$filename = 'myfile.txt';
$last_change_time = filectime($filename);

if ($last_change_time !== false) {
    $change_time_string = date('F d Y H:i:s', $last_change_time);
    echo "The file $filename had its inode changed on $change_time_string";
} else {
    echo "Could not retrieve inode change time for $filename.";
}

Nota: El parámetro filename acepta tanto rutas relativas como absolutas. Si usas una ruta relativa, se resuelve en relación con el directorio de trabajo actual.

En este ejemplo, comprobamos el tiempo de cambio de inodo de myfile.txt usando la función filectime(). Almacenamos la marca de tiempo Unix devuelta en la variable $last_change_time. El código primero verifica que la función no haya devuelto false, luego formatea la marca de tiempo con date(). Ten en cuenta que date() depende de la zona horaria predeterminada del servidor; usa date_default_timezone_set() si necesitas una salida con una zona horaria específica. Por último, mostramos un mensaje indicando cuándo cambiaron por última vez los metadatos del archivo.

Un ejemplo autónomo y ejecutable

El fragmento anterior depende de que exista un archivo en el disco. El siguiente ejemplo crea un archivo temporal, cambia sus permisos para forzar un cambio de inodo y luego lee la marca de tiempo, de modo que puedas ejecutarlo tal cual y ver una salida real:

<?php

// Create a temporary file
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, 'hello');

// Changing permissions updates the inode change time (ctime)
chmod($path, 0644);

$ctime = filectime($path);
echo "ctime: " . date('Y-m-d H:i:s', $ctime) . PHP_EOL;
echo "Is it a Unix timestamp (integer)? " . (is_int($ctime) ? 'yes' : 'no') . PHP_EOL;

unlink($path); // clean up

Esto imprime el tiempo de cambio formateado seguido de Is it a Unix timestamp (integer)? yes, lo que confirma que filectime() devuelve una marca de tiempo entera.

Cuidado con el caché de estadísticas

PHP almacena en caché el resultado de las funciones de estadísticas del sistema de archivos como filectime(), filemtime() y fileperms() durante la duración de una sola solicitud para mejorar el rendimiento. Si modificas un archivo e inmediatamente llamas a filectime() de nuevo en el mismo script, puedes obtener el valor antiguo almacenado en caché. Llama a clearstatcache() primero para obtener una lectura actualizada:

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
$first = filectime($path);

sleep(1);
chmod($path, 0600); // changes the inode

clearstatcache();   // discard the cached stat result
$second = filectime($path);

echo ($second >= $first) ? "ctime updated\n" : "still cached\n";

unlink($path);

Esto imprime ctime updated. Si eliminas la línea clearstatcache(), PHP puede reportar el valor antiguo en su lugar.

Conclusión

La función filectime() es una herramienta útil en PHP para comprobar cuándo cambió por última vez el inodo (metadatos) de un archivo: permisos, propietario o un renombrado. Recuerda que, a pesar de la "c", no es una función de tiempo de creación: usa filemtime() cuando necesites el tiempo de última modificación de contenido, fileatime() para el tiempo de último acceso, y llama a clearstatcache() cuando necesites una lectura garantizada y actualizada dentro de la misma solicitud. Combínala con file_exists() para evitar advertencias con archivos inexistentes.

Práctica