clearstatcache()

Introduction à la fonction PHP clearstatcache()

La fonction clearstatcache() vide le cache de statut des fichiers de PHP afin que le prochain appel à une fonction du système de fichiers lise des données fraîches depuis le disque.

Pour éviter d'accéder répétitivement au système de fichiers, PHP met en cache le résultat de certaines fonctions la première fois que vous les appelez sur un chemin lors d'une requête. Les fonctions qui lisent depuis ce cache (et le remplissent) incluent stat(), lstat(), file_exists(), is_writable(), is_readable(), is_file(), is_dir(), filesize(), fileperms(), fileowner(), filemtime() et fileatime().

La mise en cache accélère les vérifications répétées, mais elle signifie également que si un fichier change pendant la même requête — sa taille augmente, ses permissions changent, il est créé ou supprimé — PHP peut continuer à renvoyer la valeur obsolète en cache. clearstatcache() force PHP à oublier ce qu'il a mis en cache afin que la prochaine vérification reflète la réalité.

Le cache n'existe que pendant la durée d'une seule requête (ou d'une exécution de script CLI). Une nouvelle requête commence toujours avec un cache vide, donc clearstatcache() n'est pertinent qu'au sein d'une logique longue ou de type modifier-puis-revérifier.

Syntaxe

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

La fonction ne renvoie aucune valeur.

Paramètres

clearstatcache() accepte deux paramètres optionnels :

Appelée sans argument, clearstatcache() vide l'intégralité du cache de statut pour chaque chemin accédé jusqu'ici.

Le problème que clearstatcache() résout

La première fois que vous appelez une fonction basée sur stat sur un chemin, PHP stocke le résultat. Appelez-la à nouveau et PHP peut renvoyer la valeur en cache au lieu de relire le disque. Le risque est que quelque chose ait modifié le fichier entre-temps — principalement une modification que PHP n'a pas effectuée lui-même, comme un autre processus, le système d'exploitation ou une commande shell exécutée par votre script.

Le modèle ci-dessous lit la taille d'un fichier, laisse une commande externe le modifier, puis relit la taille. Pour s'assurer que la deuxième lecture reflète la modification, videz d'abord l'entrée en cache :

<?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);

Sortie :

First read: 5 bytes
After change: 11 bytes

Les versions modernes de PHP invalident le cache automatiquement pour de nombreuses modifications effectuées via PHP lui-même, donc vous ne verrez pas toujours une valeur obsolète. Le cache existe néanmoins bel et bien, et clearstatcache() est le moyen explicite et portable de garantir une lecture fraîche après qu'un fichier a changé en cours de requête — en particulier pour les modifications que PHP n'a pas effectuées.

Exemples

Exemple 1 : Vider l'intégralité du cache

Utile lorsque vous ne savez pas exactement quels chemins ont été mis en cache :

<?php
clearstatcache();

Exemple 2 : Vider le cache pour un fichier spécifique

Cibler un seul fichier est moins coûteux que de supprimer tout le cache. Passez true comme premier argument pour que le second prenne effet :

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

Exemple 3 : Revérifier les permissions après une modification

<?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);

Sortie :

Before: 644
After:  600

Quand l'utiliser (et quand ne pas l'utiliser)

• Utilisez-la dans les scripts qui modifient un fichier puis le réinspectent lors de la même exécution — rotateurs de journaux, observateurs de fichiers, gestionnaires d'upload vérifiant une taille sauvegardée.
• Utilisez la forme ciblée (clearstatcache(true, $path)) dans les boucles pour éviter le coût de vider tous les chemins mis en cache à chaque itération.
• Vous en avez rarement besoin dans le code requête/réponse ordinaire : chaque requête démarre avec un cache vide, donc le cache accélère simplement les vérifications répétées.

Fonctions associées

• stat() et lstat() — lisent les métadonnées complètes d'un fichier qui alimentent ce cache.
• filemtime(), filesize(), fileperms() — recherches courantes en cache affectées par le cache de statut.
• realpath() et realpath_cache_get() — le cache realpath que $clear_realpath_cache = true vide.
• PHP Filesystem — aperçu des fonctions de gestion de fichiers de PHP.

Conclusion

clearstatcache() supprime les métadonnées du système de fichiers mises en cache par PHP afin que les appels suivants tels que filesize(), filemtime() et fileperms() renvoient des valeurs actuelles. Elle est utile chaque fois que vous modifiez un fichier et le réinspectez dans la même requête. Pour de meilleures performances, videz un seul chemin avec clearstatcache(true, $path) plutôt que d'effacer l'intégralité du cache.

Pratique