filemtime()

Функция filemtime() — это встроенная функция PHP, которая возвращает время последнего изменения содержимого файла в виде Unix-временной метки. Она относится к функциям работы с файловой системой PHP и широко используется для инвалидации кэша, отображения меток «последнего обновления», а также для обнаружения изменений файла с момента последнего чтения.

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

Синтаксис

filemtime(string $filename): int|false

• $filename — путь к файлу (или директории) для проверки.
• Возвращаемое значение — время изменения в виде Unix-временной метки (секунды с 1 января 1970 UTC) при успехе, или false при ошибке.

«Время изменения» (mtime) обновляется каждый раз, когда содержимое файла записывается. Оно не изменяется при простом чтении файла или при изменении только его метаданных (прав доступа, владельца) — это время изменения inode, которое возвращает filectime().

Простой пример

Поскольку Unix-временная метка — это просто большое целое число, её обычно передают в date() для получения читаемой строки:

<?php

$filename = __FILE__; // inspect this script itself

$timestamp = filemtime($filename);
$readable  = date('F d Y H:i:s', $timestamp);

echo "The file was last modified on $readable";

__FILE__ — это магическая константа, которая всегда указывает на текущий скрипт, поэтому этот фрагмент работает без необходимости создавать отдельный файл. filemtime() возвращает временну́ю метку, а date() форматирует её (здесь: полное название месяца, день, год, затем время в 24-часовом формате).

Всегда обрабатывайте ошибки

filemtime() возвращает false, если файл не существует или недоступен для чтения, и при этом генерирует предупреждение. Поскольку false при нестрогом сравнении равно 0, никогда не передавайте результат напрямую в date() — сначала проверьте его, в идеале убедившись в существовании файла с помощью file_exists():

<?php

$filename = 'does-not-exist.txt';

if (!file_exists($filename)) {
    echo "File not found.";
} else {
    $timestamp = filemtime($filename);

    if ($timestamp === false) {
        echo "Could not read the modification time.";
    } else {
        echo "Last modified: " . date('Y-m-d H:i:s', $timestamp);
    }
}

Используйте строгое сравнение === false: настоящая временна́я метка никогда не равна false, однако == false также перехватило бы (невозможную на практике) временну́ю метку 0.

mtime vs. ctime vs. atime

PHP предоставляет доступ к трём различным временны́м меткам файла. Понимание того, какую из них использовать, помогает избежать трудноуловимых ошибок:

Для отображения времени последнего редактирования почти всегда следует использовать filemtime().

Особенность кэширования: clearstatcache()

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

<?php

$filename = tempnam(sys_get_temp_dir(), 'demo');

file_put_contents($filename, 'first write');
$first = filemtime($filename);

sleep(1);
touch($filename);          // bump the mtime

clearstatcache();          // without this, you may still see $first
$second = filemtime($filename);

echo $second > $first ? "mtime updated\n" : "mtime unchanged (cached)\n";

unlink($filename);

Здесь touch() обновляет время изменения, а clearstatcache() гарантирует, что второй вызов filemtime() отразит это изменение.

Практический пример: очистка кэша браузера

Распространённое реальное применение — добавление mtime файла к URL ресурса, чтобы браузеры повторно загружали его только при фактическом изменении файла:

<?php

$cssPath = __FILE__; // pretend this is 'styles.css'
$version = filemtime($cssPath);

echo "/assets/styles.css?v=$version";

При каждом изменении CSS-файла $version меняется, автоматически сбрасывая кэш браузера.

Заключение

filemtime() сообщает, когда содержимое файла было последний раз изменено, в виде Unix-временной метки, и возвращает false при ошибке. Используйте её вместе с date() для форматирования результата, проверяйте на false, не забывайте вызывать clearstatcache() при повторном обращении к только что изменённому файлу, и обращайтесь к filectime() или fileatime(), когда нужно время изменения метаданных или время доступа. Для получения полной статистики файла за один вызов используйте stat().

Практика