fileatime()

Что делает функция fileatime()

Функция fileatime() — встроенная функция PHP, которая возвращает время последнего обращения к файлу, то есть момент последнего чтения его содержимого. Значение возвращается в виде целочисленной Unix-временной метки (количество секунд с 1 января 1970 года, UTC), которую обычно форматируют с помощью date() перед отображением пользователю.

На этой странице рассматриваются синтаксис, возвращаемое значение, выполняемый пример, отличие времени обращения от времени изменения и изменения статуса, а также распространённая ловушка, связанная с кешированием.

Синтаксис

fileatime(string $filename): int|false

• $filename — путь к файлу, который требуется проверить. Может быть относительным (разрешается относительно рабочего каталога скрипта) или абсолютным.
• Возвращаемое значение — целочисленная Unix-временная метка при успехе или false при ошибке (например, если файл не существует или нет прав на выполнение stat). Поскольку false является допустимым значением в PHP, всегда сравнивайте результат с помощью !== false, а не через нестрогую проверку на истинность.

Важно о времени обращения в Linux. На современных Linux-системах параметры монтирования, такие как noatime или relatime, намеренно препятствуют обновлению времени обращения при каждом чтении, чтобы уменьшить количество записей на диск. Если fileatime() не изменяется после чтения файла, это настройка файловой системы, а не ошибка в вашем коде.

Как использовать fileatime()

1. Вызовите fileatime(), передав путь к файлу, который нужно проверить.
2. Сравните результат с false перед использованием, чтобы отсутствующий файл не вызывал предупреждение при передаче в date().
3. Отформатируйте временную метку с помощью date(), чтобы превратить её в читаемую строку.

<?php

// Create a small file so the example is self-contained and runnable.
$filename = 'example.txt';
file_put_contents($filename, "Hello, fileatime!\n");

// Read it back to register an access.
$contents = file_get_contents($filename);

$lastAccess = fileatime($filename);

if ($lastAccess !== false) {
    $when = date('Y-m-d H:i:s', $lastAccess);
    echo "The file {$filename} was last accessed on {$when}.\n";
} else {
    echo "Could not read the access time for {$filename}.\n";
}

unlink($filename); // tidy up

Этот скрипт создаёт example.txt, читает его, а затем запрашивает у fileatime() время последнего обращения. Защита !== false позволяет корректно обработать ситуацию с отсутствующим или недоступным файлом без генерации предупреждения. Вывод выглядит следующим образом:

The file example.txt was last accessed on 2026-06-21 10:42:07.

fileatime() vs. filemtime() vs. filectime()

PHP предоставляет три тесно связанных временных метки. Важно выбрать правильную:

Если нужно узнать, когда файл последний раз открывался, используйте fileatime(). Если нужно узнать, когда данные последний раз изменились (типичный случай для инвалидации кеша), используйте filemtime().

Ловушка с кешированием

PHP кеширует результат функций, проверяющих статус файла, таких как fileatime(), filemtime() и stat(), на протяжении всего запроса. Если вы снова читаете файл и повторно проверяете время обращения в том же скрипте, вы можете получить устаревшее значение. Очистите кеш с помощью clearstatcache() перед повторным чтением:

<?php

$filename = 'example.txt';
file_put_contents($filename, "data\n");

$first = fileatime($filename);

clearstatcache();                       // force a fresh stat() next time
$contents = file_get_contents($filename);
clearstatcache();
$second = fileatime($filename);

echo ($second >= $first)
    ? "Access time is fresh.\n"
    : "Access time looks stale.\n";

unlink($filename);

Когда это использовать?

• Аудит файлов, к которым недавно обращались (ротация логов, очистка по принципу «наименее недавно использованного»).
• Обнаружение неиспользуемых загрузок или временных файлов, которые можно безопасно удалить.
• Диагностика того, действительно ли процесс обращается к ожидаемому файлу.

Для логики, основанной на изменениях (перестройка кеша при изменении исходных данных), используйте filemtime(). Чтобы проверить существование файла перед вызовом любой из этих функций, используйте file_exists(). Для получения полного набора метаданных за один вызов см. stat().

Итоги

fileatime() возвращает Unix-временную метку последнего обращения к файлу или false при ошибке. Всегда защищайте результат проверкой !== false, форматируйте его с помощью date() и помните о двух подводных камнях: на Linux-системах монтирование с определёнными параметрами может подавлять обновление времени обращения, а PHP кеширует результаты stat в рамках запроса, если не вызвать clearstatcache().

Практика