clearstatcache()

Introduzione alla funzione PHP clearstatcache()

La funzione clearstatcache() cancella la cache dello stato dei file di PHP, in modo che la successiva chiamata a una funzione del filesystem legga dati aggiornati dal disco.

Per evitare di accedere ripetutamente al filesystem, PHP memorizza nella cache il risultato di alcune funzioni la prima volta che vengono chiamate su un percorso durante una richiesta. Le funzioni che leggono da (e popolano) questa cache includono stat(), lstat(), file_exists(), is_writable(), is_readable(), is_file(), is_dir(), filesize(), fileperms(), fileowner(), filemtime() e fileatime().

La memorizzazione nella cache rende i controlli ripetuti veloci, ma significa anche che se un file cambia durante la stessa richiesta — la sua dimensione aumenta, i permessi cambiano, viene creato o eliminato — PHP potrebbe continuare a restituire il valore obsoleto memorizzato nella cache. clearstatcache() forza PHP a dimenticare ciò che ha memorizzato nella cache, in modo che il successivo controllo rifletta la realtà.

La cache esiste solo per la durata di una singola richiesta (o esecuzione di uno script CLI). Una nuova richiesta inizia sempre con una cache vuota, quindi clearstatcache() è rilevante solo all'interno di logiche a lunga esecuzione o di tipo modifica-poi-ricontrolla.

Sintassi

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

La funzione non restituisce alcun valore.

Parametri

clearstatcache() accetta due parametri opzionali:

Chiamata senza argomenti, clearstatcache() cancella l'intera cache stat per ogni percorso acceduto finora.

Il problema che clearstatcache() risolve

La prima volta che si chiama una funzione basata su stat su un percorso, PHP memorizza il risultato. Chiamandola di nuovo, PHP potrebbe restituire il valore memorizzato nella cache invece di rileggere il disco. Il rischio è che qualcosa abbia modificato il file nel frattempo — soprattutto un cambiamento che PHP non ha eseguito direttamente, come un altro processo, il sistema operativo o un comando shell eseguito dallo script.

Il pattern seguente legge la dimensione di un file, poi la fa modificare da un comando esterno, e poi la rilegge. Per essere sicuri che la seconda lettura rifletta la modifica, è necessario cancellare prima la voce memorizzata nella 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);

Output:

First read: 5 bytes
After change: 11 bytes

Le versioni moderne di PHP invalidano automaticamente la cache per molte modifiche effettuate tramite PHP stesso, quindi potrebbe non essere sempre visibile un valore obsoleto. La cache esiste comunque, e clearstatcache() è il modo esplicito e portabile per garantire una lettura aggiornata dopo che un file cambia durante la richiesta — soprattutto per le modifiche che PHP non ha eseguito.

Esempi

Esempio 1: Cancellare l'intera cache

Utile quando non si sa esattamente quali percorsi sono stati memorizzati nella cache:

<?php
clearstatcache();

Esempio 2: Cancellare la cache per un file specifico

Puntare a un singolo file è meno costoso che scartare l'intera cache. Passare true come primo argomento affinché il secondo argomento abbia effetto:

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

Esempio 3: Ricontrollare i permessi dopo una modifica

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

Output:

Before: 644
After:  600

Quando usarla (e quando non farlo)

• Usala negli script che modificano un file e poi lo ri-ispezionano nella stessa esecuzione — rotatori di log, file watcher, gestori di upload che verificano una dimensione salvata.
• Usa la forma mirata (clearstatcache(true, $path)) nei cicli per evitare il costo di cancellare tutti i percorsi memorizzati nella cache a ogni iterazione.
• Raramente è necessaria nel normale codice richiesta/risposta: ogni richiesta inizia con una cache vuota, quindi la cache rende semplicemente veloci i controlli ripetuti.

Funzioni correlate

• stat() e lstat() — leggono i metadati completi del file che popolano questa cache.
• filemtime(), filesize(), fileperms() — consultazioni comuni memorizzate nella cache interessate dalla cache stat.
• realpath() e realpath_cache_get() — la cache realpath che $clear_realpath_cache = true cancella.
• PHP Filesystem — panoramica delle funzioni PHP per la gestione dei file.

Conclusione

clearstatcache() elimina i metadati del filesystem memorizzati nella cache da PHP, in modo che le chiamate successive come filesize(), filemtime() e fileperms() restituiscano valori aggiornati. È importante ogni volta che si modifica un file e lo si ri-ispeziona all'interno della stessa richiesta. Per le migliori prestazioni, cancellare un singolo percorso con clearstatcache(true, $path) piuttosto che svuotare l'intera cache.

Pratica