clearstatcache()

Einführung in die PHP-Funktion clearstatcache()

Die Funktion clearstatcache() leert PHPs Dateistatus-Cache, damit der nächste Aufruf einer Dateisystemfunktion frische Daten von der Festplatte liest.

Um wiederholte Zugriffe auf das Dateisystem zu vermeiden, speichert PHP das Ergebnis bestimmter Funktionen beim ersten Aufruf für einen Pfad innerhalb einer Anfrage im Cache. Zu den Funktionen, die diesen Cache befüllen und daraus lesen, gehören stat(), lstat(), file_exists(), is_writable(), is_readable(), is_file(), is_dir(), filesize(), fileperms(), fileowner(), filemtime() und fileatime().

Caching macht wiederholte Prüfungen schnell, bedeutet aber auch: Ändert sich eine Datei während derselben Anfrage — wächst ihre Größe, ändern sich ihre Berechtigungen, sie wird erstellt oder gelöscht — gibt PHP möglicherweise weiterhin den veralteten zwischengespeicherten Wert zurück. clearstatcache() zwingt PHP, den Cache zu vergessen, sodass die nächste Prüfung die tatsächliche Realität widerspiegelt.

Der Cache existiert nur für die Dauer einer einzelnen Anfrage (oder eines CLI-Skriptlaufs). Eine neue Anfrage startet immer mit einem leeren Cache, daher ist clearstatcache() nur innerhalb langlaufender Skripte oder bei Logik relevant, die nach einer Änderung erneut prüft.

Syntax

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

Die Funktion gibt keinen Wert zurück.

Parameter

clearstatcache() nimmt zwei optionale Parameter entgegen:

Ohne Argumente aufgerufen, leert clearstatcache() den gesamten Stat-Cache für alle bisher berührten Pfade.

Das Problem, das clearstatcache() löst

Beim ersten Aufruf einer stat-basierten Funktion für einen Pfad speichert PHP das Ergebnis. Bei einem erneuten Aufruf kann PHP statt einer erneuten Festplattenprüfung den zwischengespeicherten Wert zurückgeben. Das Risiko besteht darin, dass sich die Datei zwischenzeitlich geändert hat — vor allem durch eine Änderung, die PHP selbst nicht vorgenommen hat, wie ein anderer Prozess, das Betriebssystem oder ein Shell-Befehl, der vom Skript ausgeführt wird.

Das folgende Muster liest die Dateigröße, lässt dann einen externen Befehl sie ändern und liest die Größe erneut. Um sicherzustellen, dass der zweite Lesezugriff die Änderung widerspiegelt, muss der gecachte Eintrag zunächst geleert werden:

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

Ausgabe:

First read: 5 bytes
After change: 11 bytes

Moderne PHP-Versionen invalidieren den Cache automatisch für viele Änderungen, die durch PHP selbst vorgenommen werden, sodass man nicht immer einen veralteten Wert sieht. Der Cache ist dennoch real, und clearstatcache() ist die explizite, portable Methode, um nach einer Dateiänderung während einer Anfrage einen frischen Lesezugriff zu garantieren — insbesondere für Änderungen, die PHP nicht selbst durchgeführt hat.

Beispiele

Beispiel 1: Den gesamten Cache leeren

Nützlich, wenn nicht genau bekannt ist, welche Pfade gecacht wurden:

<?php
clearstatcache();

Beispiel 2: Den Cache für eine bestimmte Datei leeren

Eine einzelne Datei anzusprechen ist günstiger als den gesamten Cache zu verwerfen. Das erste Argument muss true sein, damit das zweite Argument wirksam wird:

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

Beispiel 3: Berechtigungen nach einer Änderung erneut prüfen

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

Ausgabe:

Before: 644
After:  600

Wann verwenden (und wann nicht)

• Verwenden, wenn Skripte eine Datei ändern und diese noch im selben Lauf erneut prüfen — Log-Rotatoren, Datei-Watcher, Upload-Handler, die eine gespeicherte Dateigröße verifizieren.
• Die gezielte Form verwenden (clearstatcache(true, $path)) in Schleifen, um die Kosten des vollständigen Cache-Leerens bei jeder Iteration zu vermeiden.
• Selten nötig im normalen Request-Response-Betrieb: Jede Anfrage startet frisch, sodass der Cache wiederholte Prüfungen einfach beschleunigt.

Verwandte Funktionen

• stat() und lstat() — lesen vollständige Datei-Metadaten, die diesen Cache befüllen.
• filemtime(), filesize(), fileperms() — häufige gecachte Abfragen, die vom Stat-Cache betroffen sind.
• realpath() und realpath_cache_get() — der Realpath-Cache, den $clear_realpath_cache = true leert.
• PHP Filesystem — Übersicht über PHPs Dateiverarbeitungsfunktionen.

Fazit

clearstatcache() verwirft PHPs gecachte Dateisystem-Metadaten, sodass nachfolgende Aufrufe wie filesize(), filemtime() und fileperms() aktuelle Werte zurückgeben. Die Funktion ist immer dann relevant, wenn eine Datei geändert und innerhalb derselben Anfrage erneut geprüft wird. Für optimale Performance empfiehlt sich das gezielte Leeren eines einzelnen Pfads mit clearstatcache(true, $path) anstelle des vollständigen Cache-Leerens.

Übungen