clearstatcache()

Введение в функцию PHP clearstatcache()

Функция clearstatcache() очищает кэш состояния файлов PHP, чтобы следующий вызов функции файловой системы считал свежие данные с диска.

Чтобы не обращаться к файловой системе при каждом вызове, PHP кэширует результат ряда функций при первом обращении к пути в рамках одного запроса. Функции, читающие из этого кэша (и заполняющие его): stat(), lstat(), file_exists(), is_writable(), is_readable(), is_file(), is_dir(), filesize(), fileperms(), fileowner(), filemtime() и fileatime().

Кэширование ускоряет повторные проверки, но создаёт риск: если файл изменился в ходе того же запроса — вырос его размер, сменились права доступа, файл был создан или удалён — PHP может продолжать возвращать устаревшее кэшированное значение. clearstatcache() заставляет PHP забыть закэшированные данные, и следующая проверка отразит реальное состояние.

Кэш существует только в течение одного запроса (или запуска CLI-скрипта). Каждый новый запрос начинается с пустым кэшем, поэтому clearstatcache() нужна только в долгоживущих сценариях или в логике «изменить — перепроверить».

Синтаксис

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

Функция не возвращает значения.

Параметры

clearstatcache() принимает два необязательных параметра:

При вызове без аргументов clearstatcache() очищает весь кэш состояния для всех затронутых путей.

Проблема, которую решает clearstatcache()

При первом вызове stat-функции для пути PHP сохраняет результат. При повторном вызове PHP может вернуть закэшированное значение вместо повторного чтения диска. Риск в том, что файл мог измениться между вызовами — особенно если изменение выполнено не самим PHP, а другим процессом, операционной системой или shell-командой внутри скрипта.

В примере ниже считывается размер файла, затем внешняя команда изменяет его, после чего размер считывается снова. Чтобы второй результат отражал изменение, нужно сначала очистить кэшированную запись:

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

Вывод:

First read: 5 bytes
After change: 11 bytes

Современные версии PHP автоматически инвалидируют кэш для многих изменений, выполненных самим PHP, поэтому устаревшее значение можно увидеть не всегда. Тем не менее кэш реально существует, и clearstatcache() — явный переносимый способ гарантировать свежий результат после изменения файла в ходе запроса, особенно если изменение сделано не PHP.

Примеры

Пример 1: Очистить весь кэш

Полезно, когда неизвестно, какие именно пути были закэшированы:

<?php
clearstatcache();

Пример 2: Очистить кэш для конкретного файла

Указание конкретного файла дешевле, чем сброс всего кэша. Первым аргументом передайте true, чтобы второй аргумент возымел эффект:

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

Пример 3: Перепроверка прав доступа после изменения

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

Вывод:

Before: 644
After:  600

Когда использовать (и когда не стоит)

• Используйте в скриптах, которые изменяют файл и затем повторно проверяют его в том же запуске — ротаторы логов, файловые наблюдатели, обработчики загрузки, проверяющие сохранённый размер.
• Используйте адресный вариант (clearstatcache(true, $path)) в циклах, чтобы не сбрасывать весь кэш на каждой итерации.
• В большинстве случаев не нужна в обычном коде запрос/ответ: каждый запрос начинается с чистого кэша, так что кэш лишь ускоряет повторные проверки.

Связанные функции

• stat() и lstat() — читают полные метаданные файла, заполняя этот кэш.
• filemtime(), filesize(), fileperms() — распространённые кэшируемые обращения, на которые влияет stat-кэш.
• realpath() и realpath_cache_get() — кэш realpath, очищаемый при $clear_realpath_cache = true.
• PHP Filesystem — обзор функций PHP для работы с файлами.

Заключение

clearstatcache() удаляет закэшированные метаданные файловой системы PHP, чтобы последующие вызовы — такие как filesize(), filemtime() и fileperms() — возвращали актуальные значения. Функция важна в тех случаях, когда файл изменяется и повторно проверяется в рамках одного запроса. Для лучшей производительности очищайте один путь с помощью clearstatcache(true, $path), а не весь кэш целиком.

Практика