disk_free_space()

Introduction to the PHP disk_free_space() Function

The disk_free_space() function returns the number of available bytes on the file system that contains a given directory. It's a go-to tool for server administrators and web developers who need to monitor disk usage before writing uploads, generating reports, or rotating logs — so an application can warn (or refuse to write) before the disk fills up.

A key point to understand up front: the path you pass identifies a file system, not a single folder. Whether you pass /, /home, or /home/user/uploads, PHP looks up the mounted file system that path lives on and reports the free space for the whole mount. The value is a float because disks easily exceed the range of a 32-bit integer.

This chapter covers the syntax, parameters, return value, and practical examples — including how to convert the raw byte count into a human-readable size and how to calculate the percentage of disk used.

Syntax

disk_free_space(string $directory): float|false

The function takes a single argument and returns the number of free bytes as a float, or false on failure (for example, when the directory does not exist). Note that diskfreespace() is an alias of this function and behaves identically.

Parameters

The disk_free_space() function takes one required parameter:

• $directory — A string path to any file or directory on the file system you want to inspect. The function reports the free space of the mount that contains this path, not the size of the directory itself.

Return value

On success, disk_free_space() returns the available space in bytes as a float. On failure it returns false and emits a warning, so always validate the path or check the result before relying on it.

Examples

Example 1: Get the free space on a file system

Pass the root directory to inspect the file system the operating system is installed on:

<?php

$bytes = disk_free_space("/");

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

The exact number depends on your machine; on a disk with about 20 GB free this prints 21474836480.

Example 2: Format the result as a human-readable size

A raw byte count is hard to read. This helper converts bytes into the nearest unit (KB, MB, GB, …):

<?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

Output:

20 GB
1.5 KB

Example 3: Calculate the percentage of disk used

Combine disk_free_space() with disk_total_space() to report how full a volume is:

<?php

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

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

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

For a 100 GB disk with 20 GB free this prints Disk usage: 80%.

Example 4: Guard a write with an error check

Because the function returns false on a bad path, check the result before acting on it:

<?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.";
}

Common pitfalls

• It measures the mount, not the folder. To find the size of a directory's contents, you need to sum file sizes (see filesize()) — disk_free_space() won't do that.
• Handle false. A non-existent or unreadable path returns false and triggers a warning. Validate input before passing it in.
• The result is a float. Don't compare it with integers using ===, and don't assume it fits in a 32-bit int — large disks overflow.
• open_basedir restrictions can cause the call to fail on shared hosting if the path lies outside the allowed directories.

Conclusion

The disk_free_space() function reports the available bytes on the file system containing a given path — essential for monitoring storage and guarding writes against a full disk. Pair it with disk_total_space() to compute usage percentages, format the raw byte value for display, and always check for a false return. For more on PHP's built-in functions, see the PHP functions chapter.

Practice