diskfreespace()

Введение в функцию PHP diskfreespace()

Функция diskfreespace() возвращает количество байт свободного пространства на файловой системе или разделе диска, содержащем указанный каталог. Она полезна, когда нужно проверить ёмкость перед записью больших файлов, создать панели мониторинга сервера или предупредить администратора о нехватке места.

diskfreespace() является простым псевдонимом функции disk_free_space() — оба имени вызывают одну и ту же реализацию на C и ведут себя идентично. Вариант с подчёркиванием является каноническим именем в документации PHP; вариант без подчёркивания существует для обратной совместимости. В новом коде рекомендуется использовать disk_free_space(), однако diskfreespace() по-прежнему встречается в старых кодовых базах.

В этой главе рассматриваются синтаксис, единственный аргумент функции, возвращаемые значения, выполняемые примеры и типичные подводные камни.

Синтаксис

diskfreespace(string $directory): float|false

Функция принимает один обязательный аргумент и возвращает свободное пространство в виде числа байт с плавающей точкой. Тип float используется (а не int), потому что современные диски могут хранить значительно больше байт, чем способно представить 32-битное целое число. При ошибке возвращается false.

Параметр

• $directory (string, required) — Каталог файловой системы, которую нужно проверить (например "/", "C:" или "." для текущего каталога). PHP измеряет раздел, на котором находится этот каталог, а не размер самого каталога. Путь должен указывать на каталог; передача пути к обычному файлу вызывает предупреждение и возвращает false.

Возвращаемое значение

• При успехе: float — количество свободных байт на разделе.
• При ошибке (путь не существует, не является каталогом или недоступен для чтения): false и предупреждение E_WARNING.

Примеры

Пример 1: Свободное пространство на текущем разделе

Наиболее переносимый вызов использует "." (текущий каталог), который работает в любой операционной системе:

<?php
$bytes = diskfreespace(".");
echo $bytes, " bytes free\n";

Результат — необработанное количество байт, например:

123456789012 bytes free

Пример 2: Форматирование результата в удобочитаемый размер

Необработанные байты трудно читать. Этот вспомогательный код преобразует значение в КБ / МБ / ГБ / ТБ:

<?php
function humanSize(float $bytes): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];
    $i = 0;
    while ($bytes >= 1024 && $i < count($units) - 1) {
        $bytes /= 1024;
        $i++;
    }
    return round($bytes, 2) . ' ' . $units[$i];
}

echo humanSize(123456789012); // 114.98 GB

Вывод:

114.98 GB

Пример 3: Проверка конкретного пути и обработка ошибки

Всегда проверяйте результат на false перед его использованием, поскольку путь может оказаться недействительным:

<?php
$path = "/no/such/directory";
$free = @diskfreespace($path);

if ($free === false) {
    echo "Could not read free space for $path";
} else {
    echo "Free: $free bytes";
}

Символ @ подавляет предупреждение, позволяя обработать ошибку с выводом собственного сообщения.

Типичные подводные камни

• Измеряется раздел, а не папка. Вызов diskfreespace("/var/www") сообщает о свободном пространстве на диске, где находится /var/www, а не о размере самой этой папки.
• Передавайте каталог, а не файл. Путь к файлу (например "/etc/hosts") вернёт false и вызовет предупреждение.
• Пути в Windows. Используйте букву диска, например "C:", а не путь в стиле Unix.
• Свободное и доступное пространство. На некоторых файловых системах часть «свободного» пространства зарезервирована для суперпользователя, поэтому значение может незначительно отличаться от того, которое реально доступно непривилегированному процессу.

Связанные функции

• disk_free_space() — каноническое имя этой самой функции.
• disk_total_space() — общая ёмкость раздела; в сочетании с данной функцией позволяет вычислить процент использованного пространства.
• filesize() — размер отдельного файла в байтах.

Заключение

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

Практика