PHP clearstatcache() Function: Syntax, Usage, and Important Considerations

clearstatcache() Function Syntax

bool clearstatcache([bool $clear_realpath_cache = false, string $filename = null])

The function accepts two optional parameters. $clear_realpath_cache determines whether to clear the realpath cache (default false). $filename specifies a particular file whose cache should be cleared (default null, meaning all caches).

Usage of clearstatcache()

1. Clear all caches

Calling the function without arguments clears all file status caches. clearstatcache(); After this call, subsequent file status queries will read fresh information from the filesystem.

2. Clear a specific file's cache

Pass the target filename as the second argument (optionally set the first argument to true to also clear the realpath cache). clearstatcache(true, 'test.txt'); This clears the cache for test.txt, forcing future status checks to re‑read the file.

3. Clear the realpath cache

Set the first argument to true to clear the realpath cache while leaving other caches untouched. clearstatcache(true); This removes both the file status cache and the realpath cache, though it may impact performance because PHP must recompute real paths.

Important Considerations

The function only clears caches maintained by PHP itself; it cannot affect operating‑system or external application caches.

It clears caches created by PHP functions such as file_exists(), is_file(), etc., but not those from low‑level system calls like stat() or lstat().

It does not clear other cache types such as opcode or page caches.

It operates only on the current process's cache, not on caches of other processes.

Summary

The clearstatcache() function provides a way to purge PHP's file status cache, ensuring that file‑related functions return up‑to‑date information; however, developers should use it judiciously, especially when clearing the realpath cache, to avoid unnecessary performance penalties.