lstat()

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

lstat() собирает статистику (размер, временны́е метки, владельца, права доступа и многое другое) о файле, указанном в $filename. Буква «l» означает link (ссылка): в отличие от stat(), которая следует по символической ссылке и возвращает данные о цели, на которую она указывает, lstat() возвращает данные о самой ссылке.

Это различие важно только для символических ссылок. Когда $filename — обычный файл, lstat() и stat() возвращают одинаковые данные.

На этой странице рассматриваются синтаксис, возвращаемый массив, запускаемый пример, сравнивающий её с stat(), а также типичные подводные камни.

Синтаксис

lstat(string $filename): array|false

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

Запускаемый пример

Приведённый ниже скрипт создаёт реальный файл и символическую ссылку, указывающую на него, затем проверяет оба объекта с помощью lstat() и stat(), чтобы вы могли увидеть разницу:

<?php

$target = sys_get_temp_dir() . '/lstat_target.txt';
$link   = sys_get_temp_dir() . '/lstat_link';

file_put_contents($target, 'hello');   // 5-byte target file
@unlink($link);
symlink($target, $link);

$linkInfo   = lstat($link);   // the link itself
$targetInfo = stat($link);    // follows the link to the target

echo "Link size (lstat):  {$linkInfo['size']} bytes\n";
echo "Target size (stat): {$targetInfo['size']} bytes\n";
echo "Link modified:      " . date('Y-m-d', $linkInfo['mtime']) . "\n";

unlink($link);
unlink($target);

Типичный вывод:

Link size (lstat):  65 bytes
Target size (stat): 5 bytes
Link modified:      2026-06-20

Размер, возвращаемый lstat(), — это длина данных пути символической ссылки, а не размер файла, на который она указывает. Именно эту информацию stat() скрывает от вас.

Возвращаемый массив

lstat() возвращает ту же структуру, что и stat(): массив из 26 элементов, где каждое значение присутствует дважды — один раз под числовым индексом и один раз под понятным строковым ключом. Для удобства чтения всегда предпочтительнее использовать именованные ключи:

Поскольку именованные и числовые ключи содержат одни и те же значения, $info['size'] и $info[7] взаимозаменяемы — но именованная форма значительно удобнее для чтения.

Когда использовать lstat() вместо stat()

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

Чтобы проверить, является ли путь символической ссылкой, прежде чем вызывать lstat(), используйте её вместе с is_link(). Чтобы узнать, куда указывает ссылка, используйте readlink(), а чтобы создать ссылку — symlink().

Подводные камни

• Устаревший кеш stat. PHP кеширует результаты stat/lstat в рамках одного запроса. Если файл изменился в процессе выполнения, перед повторным чтением вызовите clearstatcache(true, $filename).
• Windows. Символические ссылки существуют в Windows, но для их создания требуются повышенные привилегии; поведение может отличаться от POSIX-систем.
• Права доступа. Процессу PHP необходим доступ на чтение к директории, содержащей ссылку. На защищённых системах модули безопасности (такие как SELinux или ограничения open_basedir) могут блокировать доступ, даже если права на файл выглядят корректно.

Заключение

lstat() возвращает метаданные символической ссылки без её разыменования — то единственное, чего stat() сделать не может. Используйте её всякий раз, когда нужно проверить сами ссылки, а не их цели; читайте значения по именованным ключам и всегда проверяйте возврат false перед использованием результата.

Практика