filectime()

Что такое функция filectime()?

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

Распространённое заблуждение: filectime() — это не время создания файла. Буква «c» означает change (изменение), а не create (создание). Время изменения inode обновляется каждый раз, когда изменяются метаданные файла — например при выполнении chmod, chown, переименовании файла или даже при редактировании его содержимого (что также затрагивает метаданные). В PHP нет переносимой функции для получения истинного времени создания файла.

Используйте нужную функцию в зависимости от задачи:

• filectime() — когда последний раз изменялся inode (метаданные) файла (права, владелец, количество ссылок, переименование).
• filemtime() — когда последний раз изменялось содержимое файла.
• fileatime() — когда файл последний раз был открыт (прочитан).

Базовый синтаксис функции filectime():

Синтаксис PHP для filectime()

filectime(string $filename): int|false

Где $filename — путь к проверяемому файлу. Функция возвращает время изменения inode в виде Unix-метки времени или false (с предупреждением E_WARNING), если файл не существует или к нему нет доступа. Поскольку false и метка времени могут выглядеть одинаково при нестрогом сравнении (на практике метка времени никогда не равна 0, но важно писать защитный код), всегда проверяйте результат с помощью оператора строгого сравнения !== false.

Как использовать функцию filectime()?

Использование функции filectime() не вызывает затруднений. Вот шаги:

1. Вызовите функцию filectime(), передав имя файла, который нужно проверить.
2. Функция вернёт Unix-метку времени, представляющую время изменения inode, или false в случае ошибки.
3. Метку времени можно отформатировать с помощью функции date(), чтобы вывести время в удобочитаемом виде.

Пример кода, демонстрирующий использование функции filectime():

Как использовать функцию filectime()?

<?php

$filename = 'myfile.txt';
$last_change_time = filectime($filename);

if ($last_change_time !== false) {
    $change_time_string = date('F d Y H:i:s', $last_change_time);
    echo "The file $filename had its inode changed on $change_time_string";
} else {
    echo "Could not retrieve inode change time for $filename.";
}

Примечание: параметр filename принимает как относительные, так и абсолютные пути. При использовании относительного пути он разрешается относительно текущего рабочего каталога.

В этом примере мы проверяем время изменения inode файла myfile.txt с помощью функции filectime(). Возвращённая Unix-метка времени сохраняется в переменной $last_change_time. Код сначала проверяет, что функция не вернула false, затем форматирует метку времени с помощью date(). Обратите внимание, что date() опирается на часовой пояс сервера по умолчанию; используйте date_default_timezone_set(), если вам нужен конкретный часовой пояс. Наконец, выводится сообщение о том, когда последний раз изменялись метаданные файла.

Самодостаточный запускаемый пример

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

<?php

// Create a temporary file
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, 'hello');

// Changing permissions updates the inode change time (ctime)
chmod($path, 0644);

$ctime = filectime($path);
echo "ctime: " . date('Y-m-d H:i:s', $ctime) . PHP_EOL;
echo "Is it a Unix timestamp (integer)? " . (is_int($ctime) ? 'yes' : 'no') . PHP_EOL;

unlink($path); // clean up

Этот код выводит отформатированное время изменения, а затем строку Is it a Unix timestamp (integer)? yes, подтверждая, что filectime() возвращает целочисленную метку времени.

Предостережение о кешировании stat

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

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
$first = filectime($path);

sleep(1);
chmod($path, 0600); // changes the inode

clearstatcache();   // discard the cached stat result
$second = filectime($path);

echo ($second >= $first) ? "ctime updated\n" : "still cached\n";

unlink($path);

Этот код выведет ctime updated. Удалите строку clearstatcache(), и PHP может вернуть старое значение.

Заключение

Функция filectime() — полезный инструмент PHP для проверки того, когда последний раз изменялся inode файла (метаданные) — права доступа, владелец или переименование. Помните, что несмотря на букву «c», это не функция получения времени создания: используйте filemtime(), когда нужно время последнего изменения содержимого, fileatime() — для получения времени последнего обращения, и вызывайте clearstatcache(), когда в рамках одного запроса нужно гарантированно свежее значение. Используйте её совместно с file_exists(), чтобы избежать предупреждений при отсутствии файла.

Практика