stat()

Введение

Функция stat() возвращает единый массив, содержащий низкоуровневые метаданные о файле: размер, права доступа, владельца, номер inode, количество ссылок и три временны́х метки (доступа, изменения и изменения inode). Это обёртка PHP вокруг системного вызова C stat(), поэтому за один вызов она предоставляет ту же информацию, которую иначе пришлось бы собирать из множества отдельных функций, таких как filesize(), filemtime() и fileperms().

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

Синтаксис

stat(string $filename): array|false

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

stat() следует по символическим ссылкам и возвращает данные о целевом файле. Если вам нужны метаданные о самой ссылке, используйте lstat(). Чтобы получить статистику файла по уже открытому дескриптору, используйте fstat().

Что возвращает stat()

Возвращаемый массив необычен: каждое значение присутствует дважды — под числовым индексом и под именованным строковым ключом. Таким образом, $info[7] и $info['size'] — одно и то же значение. Двойная индексация существует для обратной совместимости; для удобочитаемого кода предпочтительнее использовать именованные ключи.

Несколько замечаний:

• mode содержит как тип файла, так и биты прав доступа. Чтобы получить только биты прав доступа Unix (например, 0644), используйте маску & 0777; для отображения в восьмеричном виде оберните результат в decoct().
• ctime — это время изменения inode (когда в последний раз изменились права доступа, владелец или ссылки), а не время создания файла. Большинство файловых систем Unix вообще не хранят время создания файла.
• Значения rdev, blksize и blocks не имеют смысла в Windows.

Пример: чтение метаданных файла

В этом примере создаётся временный файл, выполняется его статистика и выводятся размер, права доступа и время изменения:

<?php

// Create a small file to inspect.
$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "Hello, stat()!");

$info = stat($path);
if ($info === false) {
    echo "Could not stat the file.";
    exit;
}

echo "Size: {$info['size']} bytes\n";
echo "Permissions: " . decoct($info['mode'] & 0777) . "\n";
echo "Modified: " . date('Y-m-d H:i:s', $info['mtime']) . "\n";

unlink($path); // clean up

Вывод (конкретные права доступа и время зависят от вашей системы):

Size: 14 bytes
Permissions: 600
Modified: 2026-06-21 12:00:00

Всегда защищайтесь от false: при передаче несуществующего пути функция выдаёт предупреждение и возвращает false, а обращение по индексу к false вызовет ошибку.

Подводный камень: кэш статистики

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

<?php

$path = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($path, "first");
echo stat($path)['size'], "\n"; // 5

file_put_contents($path, "much longer content");
clearstatcache(true, $path);    // refresh cached metadata
echo stat($path)['size'], "\n"; // 19

unlink($path);

stat() в сравнении с функциями для конкретных задач

Если вам нужна лишь одна часть информации, специализированные функции понятнее и немного быстрее:

• Размер файла → filesize()
• Время изменения → filemtime()
• Время последнего доступа → fileatime()
• Права доступа → fileperms()
• Тип файла → filetype()

Используйте stat(), когда вам нужна сразу несколько из этих характеристик, поскольку она выполняет один системный вызов вместо многих. Перед вызовом статистики вы также можете убедиться, что путь является реальным файлом, с помощью is_file() или file_exists().

Заключение

Функция stat() позволяет получить полный низкоуровневый снимок метаданных файла за один вызов. Помните: проверяйте возвращаемое значение на false, используйте именованные ключи массива для удобочитаемости, применяйте маску mode & 0777 для получения прав доступа и очищайте кэш статистики, если файл был изменён в середине выполнения скрипта. Когда вам нужен лишь один атрибут, предпочитайте соответствующую специализированную функцию.

Практика