disk_total_space()

Introducción a la función disk_total_space() de PHP

La función disk_total_space() en PHP devuelve el tamaño total, en bytes, del sistema de archivos (o partición de disco) que contiene un directorio determinado. No mide el tamaño del directorio en sí, sino que informa la capacidad del volumen subyacente. Esto la hace útil para administradores de servidores y desarrolladores web que desean monitorear la capacidad del disco, construir paneles de almacenamiento o advertir a los usuarios antes de que una subida llene una partición.

Un punto clave que suele confundir a los principiantes: el argumento es cualquier ruta en el volumen, no el nodo de dispositivo del volumen. Pasar /var/www, /home/user o simplemente / devuelve el tamaño total de la partición en la que viven esas rutas. Para saber cuánto espacio sigue disponible, combine esta función con disk_free_space() — disk_total_space() proporciona la capacidad y disk_free_space() proporciona la porción no utilizada.

Esta página cubre la sintaxis, los parámetros, el valor de retorno y ejemplos prácticos, incluyendo cómo convertir bytes sin procesar a un formato legible por humanos y cómo calcular el porcentaje de disco utilizado.

Sintaxis

La sintaxis de la función disk_total_space() es la siguiente:

La sintaxis de PHP disk_total_space()

disk_total_space(string $directory): float|false

Parámetros

La función disk_total_space() acepta un parámetro obligatorio:

1. $directory: Una ruta ubicada en el sistema de archivos que desea inspeccionar. Cualquier ruta válida en el volumen funciona — la función la resuelve hasta la partición a la que pertenece. En Windows, use una letra de unidad con una barra diagonal al final, por ejemplo C:\ o C:/.

Valor de retorno

La función devuelve el número total de bytes en el sistema de archivos como un float (se usa un float porque los volúmenes pueden superar el rango de un entero de 32 bits). En caso de fallo — por ejemplo, una ruta no válida o un error de permisos — devuelve false. Dado que un tamaño de disco válido podría en teoría coincidir con un valor que PHP trata como falso, siempre compruebe el resultado con la comparación estricta !== false en lugar de una verificación de veracidad flexible.

Ejemplos

A continuación se presentan algunos ejemplos de cómo usar la función disk_total_space():

Ejemplo 1: Obtener el tamaño total de un sistema de archivos

El siguiente ejemplo obtiene el tamaño total del sistema de archivos /home/:

Obtener el tamaño total de un sistema de archivos en PHP

echo disk_total_space("/home/");

El resultado de este ejemplo será el tamaño total del sistema de archivos en bytes.

Ejemplo 2: Obtener el tamaño total de una partición de disco

El siguiente ejemplo obtiene el tamaño total de la partición de disco /dev/sda1:

Obtener el tamaño total de una partición de disco en PHP

echo disk_total_space("/dev/sda1");

El resultado de este ejemplo será el tamaño total de la partición de disco en bytes.

Ejemplo 3: Convertir bytes a un formato legible por humanos

La función devuelve bytes sin procesar, que son difíciles de leer. Convierta el resultado a gigabytes y formatéelo con number_format():

Convertir el tamaño del disco a formato legible por humanos en PHP

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

Para una unidad que escale automáticamente (KB, MB, GB, TB, …), use un pequeño ayudante:

Formateador de bytes con escala automática en 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"

Ejemplo 4: Calcular el porcentaje de disco utilizado

Combine disk_total_space() con disk_free_space() para informar qué tan lleno está un volumen — útil para alertas y scripts de monitoreo:

Calcular el porcentaje de disco utilizado en 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}%";
}

Notas y advertencias

• Mide el volumen, no el directorio. Para obtener el tamaño del contenido de una carpeta, sume los tamaños de sus archivos (por ejemplo con filesize() al iterar), no disk_total_space().
• Siempre compruebe si devuelve false. Una ruta inexistente, una unidad desmontada o permisos insuficientes hacen que la llamada falle; use !== false.
• open-basedir / rutas seguras. Si las restricciones de open_basedir están activas, la ruta debe estar dentro de un directorio permitido o la llamada fallará.
• Función relacionada. disk_free_space() (y su alias diskfreespace()) devuelve el espacio disponible en el mismo volumen.

Conclusión

La función disk_total_space() informa la capacidad total, en bytes, del sistema de archivos que contiene una ruta determinada. Combinada con disk_free_space(), permite construir paneles de almacenamiento, aplicar límites de subida y activar alertas de espacio bajo. Recuerde los tres aspectos esenciales: pase cualquier ruta en el volumen de destino, trate el valor de retorno como un float y protéjase contra fallos con una comprobación estricta !== false.

Practice