disk_total_space()

Introduction to PHP disk_total_space() Function

The disk_total_space() function in PHP returns the total size, in bytes, of the file system (or disk partition) that contains a given directory. It does not measure the size of the directory itself — it reports the capacity of the underlying volume. This makes it useful for server administrators and web developers who want to monitor disk capacity, build storage dashboards, or warn users before an upload fills a partition.

A key point that often confuses newcomers: the argument is any path on the volume, not the volume's device node. Passing /var/www, /home/user, or simply / all return the total size of whichever partition those paths live on. To find out how much room is still available, pair this function with disk_free_space() — disk_total_space() gives the capacity and disk_free_space() gives the unused portion.

This page covers the syntax, parameters, return value, and practical examples, including how to convert raw bytes into a human-readable format and how to compute the percentage of disk used.

Syntax

The syntax of the disk_total_space() function is as follows:

The syntax of PHP disk_total_space()

disk_total_space(string $directory): float|false

Parameters

The disk_total_space() function takes one required parameter:

1. $directory: A path located on the file system you want to inspect. Any valid path on the volume works — the function resolves it to the partition it belongs to. On Windows, use a drive letter with a trailing slash, for example C:\ or C:/.

Return value

The function returns the total number of bytes on the file system as a float (a float is used because volumes can exceed the range of a 32-bit integer). On failure — for example, an invalid path or a permission error — it returns false. Because a valid disk size could in theory coincide with a value PHP treats as falsy, always test the result with the strict !== false comparison rather than a loose truthiness check.

Examples

Here are some examples of how to use the disk_total_space() function:

Example 1: Retrieve the total size of a file system

The following example retrieves the total size of the /home/ file system:

Retrieve the total size of a file system in PHP

echo disk_total_space("/home/");

The output of this example will be the total size of the file system in bytes.

Example 2: Retrieve the total size of a disk partition

The following example retrieves the total size of the /dev/sda1 disk partition:

Retrieve the total size of a disk partition in PHP

echo disk_total_space("/dev/sda1");

The output of this example will be the total size of the disk partition in bytes.

Example 3: Convert bytes to a human-readable format

The function returns raw bytes, which are hard to read. Convert the result to gigabytes and format it with number_format():

Convert disk size to human-readable format in PHP

$bytes = disk_total_space("/");
if ($bytes !== false) {
    echo number_format($bytes / 1024 / 1024 / 1024, 2) . " GB";
}
// e.g. "465.76 GB"

For a unit that scales automatically (KB, MB, GB, TB, …), use a small helper:

Auto-scaling byte formatter in PHP

function formatBytes(float $bytes, int $precision = 2): string {
    $units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
    $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(disk_total_space("/")); // e.g. "465.76 GB"

Example 4: Calculate the percentage of disk used

Combine disk_total_space() with disk_free_space() to report how full a volume is — handy for alerts and monitoring scripts:

Calculate the percentage of disk used in PHP

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

if ($total !== false && $free !== false) {
    $usedPercent = round(($total - $free) / $total * 100, 1);
    echo "Disk used: {$usedPercent}%";
}

Notes and gotchas

• It measures the volume, not the directory. To get the size of a folder's contents, sum the sizes of its files (for example with filesize() while iterating), not disk_total_space().
• Always check for false. A missing path, an unmounted drive, or insufficient permissions makes the call fail; use !== false.
• Open-basedir / safe paths. If open_basedir restrictions are active, the path must be inside an allowed directory or the call fails.
• Related function. disk_free_space() (and its alias diskfreespace()) returns the available space on the same volume.

Conclusion

The disk_total_space() function reports the total capacity, in bytes, of the file system that holds a given path. Paired with disk_free_space(), it lets you build storage dashboards, enforce upload limits, and trigger low-space alerts. Remember the three essentials: pass any path on the target volume, treat the return value as a float, and guard against failure with a strict !== false check.

Practice