PHP disk_free_space Function
last modified April 3, 2025
The PHP disk_free_space function returns the available space on
a filesystem or disk partition. It's useful for monitoring storage capacity.
Basic Definition
The disk_free_space function returns the number of bytes available
on the corresponding filesystem or disk partition. It takes one parameter.
Syntax: disk_free_space(string $directory): float|false. The
function returns false on failure. The related function is disk_total_space.
Basic disk_free_space Example
This shows the simplest usage of disk_free_space to check space.
<?php
declare(strict_types=1);
$freeSpace = disk_free_space("/");
echo "Free space on root: " . $freeSpace . " bytes";
This checks available space on the root filesystem. The result is in bytes. You may need to format it for human-readable output.
Formatting Disk Space
This example formats the raw bytes into a human-readable format.
<?php
declare(strict_types=1);
function formatBytes(float $bytes, int $precision = 2): string {
$units = ['B', 'KB', 'MB', 'GB', 'TB'];
$bytes = max($bytes, 0);
$pow = floor(($bytes ? log($bytes) : 0) / log(1024));
$pow = min($pow, count($units) - 1);
$bytes /= (1 << (10 * $pow));
return round($bytes, $precision) . ' ' . $units[$pow];
}
$free = disk_free_space("/");
echo "Free space: " . formatBytes($free);
The formatBytes function converts bytes to appropriate units.
This makes the output much easier to read and understand.
Checking Specific Directory
You can check space for any directory, not just the root filesystem.
<?php
declare(strict_types=1);
$directory = "/var/www";
$freeSpace = disk_free_space($directory);
if ($freeSpace === false) {
echo "Could not check disk space for $directory";
} else {
echo "Free space in $directory: " . $freeSpace . " bytes";
}
This checks space for the /var/www directory. Note the error handling for cases where the directory might not exist or be inaccessible.
Windows Drive Example
The function works with Windows drive letters as well.
<?php declare(strict_types=1); $drive = "C:"; $freeSpace = disk_free_space($drive); echo "Free space on $drive: " . number_format($freeSpace) . " bytes";
On Windows systems, you can check drive space by specifying the drive letter.
The number_format function makes the output more readable.
Comparing Free and Total Space
This example shows both free and total space for comparison.
<?php
declare(strict_types=1);
function formatBytes(float $bytes): string {
if ($bytes >= 1073741824) {
return number_format($bytes / 1073741824, 2) . ' GB';
} elseif ($bytes >= 1048576) {
return number_format($bytes / 1048576, 2) . ' MB';
} elseif ($bytes >= 1024) {
return number_format($bytes / 1024, 2) . ' KB';
}
return $bytes . ' bytes';
}
$directory = "/";
$free = disk_free_space($directory);
$total = disk_total_space($directory);
echo "Total space: " . formatBytes($total) . "\n";
echo "Free space: " . formatBytes($free) . "\n";
echo "Used space: " . formatBytes($total - $free);
This provides a complete picture of disk usage by showing total, free, and used space. The custom formatting function handles different size units.
Edge Cases
disk_free_space has some important edge cases to consider.
<?php
declare(strict_types=1);
// Non-existent directory
$result1 = disk_free_space("/nonexistent/path");
// No permissions
$result2 = disk_free_space("/root");
var_dump($result1); // bool(false)
var_dump($result2); // bool(false) or warning
The function returns false when it can't determine the free space. This happens with non-existent paths or insufficient permissions. Always check the return value.
Best Practices
- Error Handling: Always check for false return value.
- Permissions: Ensure PHP has access to the directory.
- Formatting: Convert bytes for human-readable output.
- Caching: Don't call frequently as it's filesystem intensive.
Source
PHP disk_free_space Documentation
This tutorial covered the PHP disk_free_space function with practical
examples showing its usage in different scenarios.