disk_free_space()

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

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

Важно понимать с самого начала: путь, который вы передаёте, идентифицирует файловую систему, а не отдельную папку. Независимо от того, передадите ли вы /, /home или /home/user/uploads, PHP определяет смонтированную файловую систему, на которой находится этот путь, и возвращает свободное место для всего раздела. Значение имеет тип float, поскольку размеры дисков легко выходят за пределы 32-битного целого числа.

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

Синтаксис

disk_free_space(string $directory): float|false

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

Параметры

Функция disk_free_space() принимает один обязательный параметр:

• $directory — строковый путь к любому файлу или каталогу на файловой системе, которую вы хотите проверить. Функция возвращает свободное место раздела, содержащего этот путь, а не размер самого каталога.

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

В случае успеха disk_free_space() возвращает доступное пространство в байтах в виде float. При сбое возвращает false и генерирует предупреждение, поэтому всегда проверяйте путь или результат перед его использованием.

Примеры

Пример 1: Получение свободного места на файловой системе

Передайте корневой каталог, чтобы проверить файловую систему, на которой установлена операционная система:

<?php

$bytes = disk_free_space("/");

echo $bytes; // e.g. 21474836480 (raw bytes)

Точное число зависит от вашей машины; на диске с примерно 20 ГБ свободного места выведет 21474836480.

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

Сырое число байт сложно воспринимать. Этот вспомогательный код преобразует байты в ближайшую единицу (КБ, МБ, ГБ, …):

<?php

function formatBytes(float $bytes, int $precision = 2): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];

    $pow = $bytes > 0 ? floor(log($bytes, 1024)) : 0;
    $pow = min($pow, count($units) - 1);

    $bytes /= 1024 ** $pow;

    return round($bytes, $precision) . ' ' . $units[$pow];
}

echo formatBytes(21474836480); // 20 GB
echo "\n";
echo formatBytes(1536);        // 1.5 KB

Вывод:

20 GB
1.5 KB

Пример 3: Вычисление процента использования диска

Совместите disk_free_space() с disk_total_space(), чтобы отобразить степень заполненности раздела:

<?php

$total = disk_total_space("/");
$free  = disk_free_space("/");
$used  = $total - $free;

$percentUsed = round(($used / $total) * 100, 1);

echo "Disk usage: {$percentUsed}%";

Для диска объёмом 100 ГБ с 20 ГБ свободного места выведет Disk usage: 80%.

Пример 4: Защита записи с проверкой ошибок

Поскольку функция возвращает false при неверном пути, проверяйте результат перед выполнением действий:

<?php

$path = "/var/www/uploads";
$free = disk_free_space($path);

if ($free === false) {
    echo "Could not read free space for {$path}";
} elseif ($free < 100 * 1024 * 1024) { // less than 100 MB
    echo "Warning: low disk space!";
} else {
    echo "Enough space to continue.";
}

Распространённые ошибки

• Измеряется раздел, а не папка. Чтобы узнать размер содержимого каталога, нужно суммировать размеры файлов (см. filesize()) — disk_free_space() этого не делает.
• Обрабатывайте false. Несуществующий или недоступный путь возвращает false и генерирует предупреждение. Проверяйте входные данные перед передачей.
• Результат имеет тип float. Не сравнивайте его с целыми числами через === и не предполагайте, что он помещается в 32-битный int — большие диски переполняют его.
• Ограничения open_basedir могут привести к сбою вызова на общем хостинге, если путь находится за пределами разрешённых каталогов.

Заключение

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

Практика