clearstatcache()

Introducción a la función clearstatcache() de PHP

La función clearstatcache() borra la caché de estado de archivos de PHP para que la siguiente llamada a una función del sistema de archivos lea datos actualizados directamente desde el disco.

Para evitar acceder al sistema de archivos repetidamente, PHP almacena en caché el resultado de ciertas funciones la primera vez que se invocan sobre una ruta durante una petición. Las funciones que leen (y pueblan) esta caché incluyen stat(), lstat(), file_exists(), is_writable(), is_readable(), is_file(), is_dir(), filesize(), fileperms(), fileowner(), filemtime() y fileatime().

El almacenamiento en caché hace que las comprobaciones repetidas sean rápidas, pero también implica que si un archivo cambia durante la misma petición — crece su tamaño, cambian sus permisos, se crea o se elimina — PHP puede seguir devolviendo el valor obsoleto almacenado en caché. clearstatcache() obliga a PHP a olvidar lo que tenía en caché, de modo que la siguiente comprobación refleje la realidad.

La caché existe únicamente durante la duración de una sola petición (o ejecución de un script CLI). Una nueva petición siempre comienza con una caché vacía, por lo que clearstatcache() solo es relevante dentro de lógica de larga duración o de modificar-y-volver-a-comprobar.

Sintaxis

clearstatcache(bool $clear_realpath_cache = false, string $filename = ""): void

La función no devuelve ningún valor.

Parámetros

clearstatcache() acepta dos parámetros opcionales:

Llamada sin argumentos, clearstatcache() borra toda la caché de stat para cada ruta procesada hasta ese momento.

El problema que resuelve clearstatcache()

La primera vez que se llama a una función basada en stat sobre una ruta, PHP almacena el resultado. Si se vuelve a llamar, PHP puede devolver el valor almacenado en lugar de releer el disco. El riesgo está en que algo haya cambiado el archivo en el intervalo — principalmente un cambio que PHP no realizó por sí mismo, como otro proceso, el sistema operativo o un comando de shell ejecutado por el script.

El siguiente patrón lee el tamaño de un archivo, luego lo modifica mediante un comando externo y después vuelve a leer el tamaño. Para asegurarse de que la segunda lectura refleja el cambio, hay que borrar antes la entrada de la caché:

<?php
$file = tempnam(sys_get_temp_dir(), 'demo');

file_put_contents($file, 'hello');
echo "First read: " . filesize($file) . " bytes\n"; // populates the cache

// Something outside PHP changes the file.
exec('printf " world" >> ' . escapeshellarg($file));

// Force PHP to forget the cached size before re-checking.
clearstatcache(true, $file);
echo "After change: " . filesize($file) . " bytes\n";

unlink($file);

Salida:

First read: 5 bytes
After change: 11 bytes

Las versiones modernas de PHP invalidan la caché automáticamente para muchos cambios realizados a través del propio PHP, por lo que es posible que no siempre se observe un valor obsoleto. Sin embargo, la caché sigue siendo real, y clearstatcache() es la forma explícita y portable de garantizar una lectura actualizada después de que un archivo cambie a mitad de una petición, especialmente para cambios que PHP no realizó.

Ejemplos

Ejemplo 1: Borrar toda la caché

Útil cuando no se sabe exactamente qué rutas fueron almacenadas en caché:

<?php
clearstatcache();

Ejemplo 2: Borrar la caché para un archivo específico

Apuntar a un solo archivo es más económico que descartar toda la caché. Se pasa true como primer argumento para que el segundo argumento tenga efecto:

<?php
clearstatcache(true, '/path/to/example.txt');

Ejemplo 3: Volver a comprobar permisos tras un cambio

<?php
$file = tempnam(sys_get_temp_dir(), 'perm');

chmod($file, 0644);
echo "Before: " . substr(sprintf('%o', fileperms($file)), -3) . "\n";

chmod($file, 0600);
clearstatcache(true, $file);
echo "After:  " . substr(sprintf('%o', fileperms($file)), -3) . "\n";

unlink($file);

Salida:

Before: 644
After:  600

Cuándo usarla (y cuándo no)

• Úsala en scripts que modifican un archivo y luego lo vuelven a inspeccionar en la misma ejecución: rotadores de logs, observadores de archivos, manejadores de subidas que verifican un tamaño guardado.
• Usa la forma específica (clearstatcache(true, $path)) dentro de bucles para evitar el costo de borrar todas las rutas en caché en cada iteración.
• Raramente la necesitarás en código de petición/respuesta ordinario: cada petición comienza con una caché vacía, por lo que la caché simplemente hace más rápidas las comprobaciones repetidas.

Funciones relacionadas

• stat() y lstat() — leen los metadatos completos de un archivo y pueblan esta caché.
• filemtime(), filesize(), fileperms() — búsquedas en caché comunes afectadas por la caché de stat.
• realpath() y realpath_cache_get() — la caché de realpath que borra $clear_realpath_cache = true.
• PHP Filesystem — descripción general de las funciones de manejo de archivos de PHP.

Conclusión

clearstatcache() descarta los metadatos del sistema de archivos almacenados en caché por PHP para que las llamadas posteriores como filesize(), filemtime() y fileperms() devuelvan valores actuales. Es relevante siempre que se modifique un archivo y se vuelva a inspeccionar dentro de la misma petición. Para un mejor rendimiento, borra una sola ruta con clearstatcache(true, $path) en lugar de vaciar toda la caché.

Práctica