clearstatcache()

Introduction to PHP clearstatcache() Function

The clearstatcache() function clears PHP's file status cache so that the next call to a filesystem function reads fresh data from disk.

To avoid hitting the filesystem repeatedly, PHP caches the result of certain functions the first time you call them on a path during a request. The functions that read from (and populate) this cache include stat(), lstat(), file_exists(), is_writable(), is_readable(), is_file(), is_dir(), filesize(), fileperms(), fileowner(), filemtime(), and fileatime().

Caching makes repeated checks fast, but it also means that if a file changes during the same request — its size grows, its permissions change, it gets created or deleted — PHP may keep returning the stale cached value. clearstatcache() forces PHP to forget what it cached so the next check reflects reality.

The cache lives only for the duration of a single request (or CLI script run). A fresh request always starts with an empty cache, so clearstatcache() is only relevant within long-running or change-then-recheck logic.

Syntax

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

The function returns no value.

Parameters

clearstatcache() takes two optional parameters:

Called with no arguments, clearstatcache() clears the entire stat cache for every path touched so far.

The problem clearstatcache() solves

The first time you call a stat-based function on a path, PHP stores the result. Call it again and PHP may hand back the cached value instead of re-reading the disk. The risk is that something changed the file in between — most importantly a change PHP did not perform itself, such as another process, the operating system, or a shell command run by your script.

The pattern below reads a file's size, then has an external command modify it, then reads the size again. To be sure the second read reflects the change, clear the cached entry first:

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

Modern PHP versions invalidate the cache automatically for many changes made through PHP itself, so you may not always see a stale value. The cache is still real, however, and clearstatcache() is the explicit, portable way to guarantee a fresh read after a file changes mid-request — especially for changes PHP didn't make.

Examples

Example 1: Clear the entire cache

Useful when you don't know exactly which paths were cached:

<?php
clearstatcache();

Example 2: Clear the cache for a specific file

Targeting one file is cheaper than discarding the whole cache. Pass true as the first argument so the second argument takes effect:

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

Example 3: Re-checking permissions after a change

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

When to use it (and when not to)

• Use it in scripts that modify a file and then re-inspect it in the same run — log rotators, file watchers, upload handlers verifying a saved size.
• Use the targeted form (clearstatcache(true, $path)) in loops to avoid the cost of clearing every cached path on each iteration.
• You rarely need it in ordinary request/response code: each request starts fresh, so the cache simply makes repeated checks fast.

Related functions

• stat() and lstat() — read full file metadata that populates this cache.
• filemtime(), filesize(), fileperms() — common cached lookups affected by the stat cache.
• realpath() and realpath_cache_get() — the realpath cache that $clear_realpath_cache = true clears.
• PHP Filesystem — overview of PHP's file-handling functions.

Conclusion

clearstatcache() discards PHP's cached filesystem metadata so subsequent calls such as filesize(), filemtime(), and fileperms() return current values. It matters whenever you change a file and re-inspect it within the same request. For best performance, clear a single path with clearstatcache(true, $path) rather than wiping the entire cache.

Practice