clearstatcache()

Introdução à função clearstatcache() do PHP

A função clearstatcache() limpa o cache de status de arquivo do PHP para que a próxima chamada a uma função de sistema de arquivos leia dados frescos do disco.

Para evitar acessos repetidos ao sistema de arquivos, o PHP armazena em cache o resultado de certas funções na primeira vez que são chamadas com um determinado caminho durante uma requisição. As funções que leem (e populam) esse cache incluem stat(), lstat(), file_exists(), is_writable(), is_readable(), is_file(), is_dir(), filesize(), fileperms(), fileowner(), filemtime() e fileatime().

O cache torna verificações repetidas rápidas, mas também significa que se um arquivo mudar durante a mesma requisição — seu tamanho aumentar, suas permissões mudarem, ele for criado ou excluído — o PHP pode continuar retornando o valor desatualizado em cache. clearstatcache() força o PHP a esquecer o que armazenou em cache, para que a próxima verificação reflita a realidade.

O cache dura apenas pelo tempo de uma única requisição (ou execução de script CLI). Uma nova requisição sempre começa com um cache vazio, então clearstatcache() só é relevante em lógicas de longa duração ou com mudança seguida de nova verificação.

Sintaxe

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

A função não retorna nenhum valor.

Parâmetros

clearstatcache() aceita dois parâmetros opcionais:

Chamada sem argumentos, clearstatcache() limpa todo o cache de stat para todos os caminhos acessados até o momento.

O problema que clearstatcache() resolve

Na primeira vez que você chama uma função baseada em stat para um caminho, o PHP armazena o resultado. Se chamada novamente, o PHP pode retornar o valor em cache em vez de reler o disco. O risco é que algo tenha alterado o arquivo no intervalo — especialmente uma mudança que o próprio PHP não realizou, como outro processo, o sistema operacional ou um comando shell executado pelo seu script.

O padrão abaixo lê o tamanho de um arquivo, depois faz um comando externo modificá-lo e, em seguida, lê o tamanho novamente. Para garantir que a segunda leitura reflita a mudança, limpe a entrada em cache primeiro:

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

Saída:

First read: 5 bytes
After change: 11 bytes

Versões modernas do PHP invalidam o cache automaticamente para muitas mudanças feitas pelo próprio PHP, então nem sempre você verá um valor desatualizado. O cache ainda existe, porém, e clearstatcache() é a forma explícita e portátil de garantir uma leitura atualizada após um arquivo mudar durante a requisição — especialmente para mudanças que o PHP não realizou.

Exemplos

Exemplo 1: Limpar todo o cache

Útil quando você não sabe exatamente quais caminhos foram armazenados em cache:

<?php
clearstatcache();

Exemplo 2: Limpar o cache de um arquivo específico

Direcionar para um arquivo é mais barato do que descartar todo o cache. Passe true como primeiro argumento para que o segundo argumento tenha efeito:

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

Exemplo 3: Reverificar permissões após uma mudança

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

Saída:

Before: 644
After:  600

Quando usar (e quando não usar)

• Use-a em scripts que modificam um arquivo e depois o inspecionam novamente na mesma execução — rotadores de log, monitores de arquivo, manipuladores de upload que verificam o tamanho salvo.
• Use a forma direcionada (clearstatcache(true, $path)) em laços para evitar o custo de limpar todos os caminhos em cache a cada iteração.
• Raramente é necessária em código comum de requisição/resposta: cada requisição começa do zero, então o cache simplesmente torna verificações repetidas rápidas.

Funções relacionadas

• stat() e lstat() — leem os metadados completos do arquivo que populam esse cache.
• filemtime(), filesize(), fileperms() — consultas em cache comuns afetadas pelo cache de stat.
• realpath() e realpath_cache_get() — o cache de realpath que $clear_realpath_cache = true limpa.
• PHP Filesystem — visão geral das funções de manipulação de arquivos do PHP.

Conclusão

clearstatcache() descarta os metadados do sistema de arquivos armazenados em cache pelo PHP para que chamadas subsequentes como filesize(), filemtime() e fileperms() retornem valores atuais. É relevante sempre que você altera um arquivo e o reinspeciona dentro da mesma requisição. Para melhor desempenho, limpe um único caminho com clearstatcache(true, $path) em vez de apagar todo o cache.

Prática