clearstatcache
Clears PHP's cached file status information so the next stat call reads fresh data from disk.
clearstatcache(bool $clear_realpath_cache = false, string $filename = ""): void- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$clear_realpath_cacheoptional | bool= false | Whether to also clear the realpath cache, which stores resolved symlink and relative-path lookups. |
$filenameoptional | string= "" | Clear the realpath cache for this filename only. Used only when clear_realpath_cache is true. |
Return value
voidNo value is returned.
Errors
Nothing. It has no failure mode and returns void.
PHP caches the result of the last stat() it performed so that a chain of checks on the same file does not hit the disk repeatedly. That cache lives for the whole request, and clearstatcache() throws it away.
Which functions are affected
stat, lstat, file_exists, is_writable, is_readable, is_executable, is_file, is_dir, is_link, filectime, fileatime, filemtime, fileinode, filegroup, fileowner, filesize, filetype and fileperms. Functions that read content, such as file_get_contents(), are not cached.
When to reach for it
In a short web request the cache is almost always invisible — the file is unlikely to change mid-request. It bites in long-running code: a CLI worker polling a file's size, a queue consumer waiting for another process to finish writing, or a test that creates a file, deletes it, and asks again. In those places call clearstatcache() immediately before the check, not after the write.
What trips people up
Misses are never cached. If file_exists() said false, a later call re-checks the disk and can return true without any cache clearing. Hits are the problem: once a file has been seen, its metadata sticks — including after it is deleted.
Example
When to use it
- A CLI worker that polls filesize() to detect when an upload or export has finished growing
- Integration tests that create, modify and delete the same temporary file inside one process
- A deploy script that checks filemtime() after another process has rewritten a cache file
- Re-checking is_writable() after permissions were changed during the same request
Frequently asked questions
Why does filesize return the old size after I write to a file?
PHP cached the file's stat data the first time you asked, and writing to the file does not invalidate that cache. Call clearstatcache() before the second filesize() to force a fresh read.
Can clearstatcache clear the cache for just one file?
Not for the stat cache — that is always cleared entirely. The filename argument only narrows the separate realpath cache, and only when the first argument is true.
Do I need clearstatcache in a normal web request?
Almost never. The cache lives for one request, so it only matters in long-running CLI scripts, workers, and tests where the same file is inspected repeatedly while it changes.
More examples
Misses are never cached
PHP deliberately does not cache the fact that a file was missing, so code waiting for a file to appear works without any cache management. The asymmetry is the point: you need clearstatcache() after metadata changes on a file PHP has already seen, not before checking for one it has not.
<?php
$file = "appears-later.txt";
var_dump(file_exists($file)); // false, and NOT remembered
file_put_contents($file, "hello");
var_dump(file_exists($file)); // true, no clearstatcache() needed
echo filesize($file), "\n"; // 5
unlink($file);A wrapper that always reads fresh
Wrapping the clear and the stat together removes the ordering mistake people usually make — clearing after the read instead of before it. The output goes 10 then 25 because every call re-reads from disk. Do not do this in a hot loop over thousands of files; each call costs a real syscall.
<?php
function freshSize(string $path): int
{
clearstatcache(true, $path);
return filesize($path);
}
$file = "growing.txt";
file_put_contents($file, str_repeat("x", 10));
echo freshSize($file), "\n"; // 10
file_put_contents($file, str_repeat("x", 25));
echo freshSize($file), "\n"; // 25
unlink($file);Stale metadata after deleting a file
Once filesize() has looked at a path, that metadata is remembered for the rest of the request. Clearing the cache before re-checking is what makes file_exists() report the deletion. The @ on the last call suppresses the expected warning for a path that is genuinely gone.
<?php
$file = "gone.txt";
file_put_contents($file, "data");
echo "size seen: ", filesize($file), "\n"; // 4, now cached
unlink($file);
clearstatcache();
var_dump(file_exists($file)); // false
var_dump(@filesize($file)); // false + E_WARNING suppressed
Discussion