disk_free_space()

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

La función disk_free_space() devuelve el número de bytes disponibles en el sistema de archivos que contiene un directorio dado. Es una herramienta esencial para administradores de servidores y desarrolladores web que necesitan monitorizar el uso del disco antes de escribir archivos subidos, generar informes o rotar registros — para que una aplicación pueda advertir (o negarse a escribir) antes de que el disco se llene.

Un punto clave que hay que entender de antemano: la ruta que se proporciona identifica un sistema de archivos, no una carpeta individual. Ya sea que se pase /, /home o /home/user/uploads, PHP busca el sistema de archivos montado en el que reside esa ruta e informa del espacio libre para todo el montaje. El valor es un float porque los discos superan fácilmente el rango de un entero de 32 bits.

Este capítulo cubre la sintaxis, los parámetros, el valor de retorno y ejemplos prácticos — incluyendo cómo convertir el recuento de bytes en bruto a un tamaño legible por humanos y cómo calcular el porcentaje de disco utilizado.

Sintaxis

disk_free_space(string $directory): float|false

La función acepta un único argumento y devuelve el número de bytes libres como un float, o false en caso de error (por ejemplo, cuando el directorio no existe). Tenga en cuenta que diskfreespace() es un alias de esta función y se comporta de manera idéntica.

Parámetros

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

• $directory — Una ruta de tipo string hacia cualquier archivo o directorio en el sistema de archivos que desea inspeccionar. La función informa del espacio libre del montaje que contiene esta ruta, no del tamaño del directorio en sí.

Valor de retorno

En caso de éxito, disk_free_space() devuelve el espacio disponible en bytes como un float. En caso de error, devuelve false y emite una advertencia, por lo que siempre se debe validar la ruta o comprobar el resultado antes de utilizarlo.

Ejemplos

Ejemplo 1: Obtener el espacio libre en un sistema de archivos

Pase el directorio raíz para inspeccionar el sistema de archivos en el que está instalado el sistema operativo:

<?php

$bytes = disk_free_space("/");

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

El número exacto depende de su máquina; en un disco con unos 20 GB libres, esto imprime 21474836480.

Ejemplo 2: Formatear el resultado como un tamaño legible por humanos

Un recuento de bytes en bruto es difícil de leer. Esta función auxiliar convierte bytes a la unidad más cercana (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

Salida:

20 GB
1.5 KB

Ejemplo 3: Calcular el porcentaje de disco utilizado

Combine disk_free_space() con disk_total_space() para informar de qué tan lleno está un volumen:

<?php

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

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

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

Para un disco de 100 GB con 20 GB libres, esto imprime Disk usage: 80%.

Ejemplo 4: Proteger una escritura con verificación de errores

Dado que la función devuelve false con una ruta incorrecta, compruebe el resultado antes de actuar sobre él:

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

Errores comunes

• Mide el montaje, no la carpeta. Para encontrar el tamaño del contenido de un directorio, es necesario sumar los tamaños de los archivos (véase filesize()) — disk_free_space() no hace eso.
• Gestione el false. Una ruta inexistente o ilegible devuelve false y activa una advertencia. Valide la entrada antes de pasarla.
• El resultado es un float. No lo compare con enteros usando ===, y no asuma que cabe en un int de 32 bits — los discos grandes desbordan.
• Las restricciones de open_basedir pueden hacer que la llamada falle en alojamientos compartidos si la ruta está fuera de los directorios permitidos.

Conclusión

La función disk_free_space() informa de los bytes disponibles en el sistema de archivos que contiene una ruta dada — esencial para monitorizar el almacenamiento y proteger las escrituras ante un disco lleno. Combínela con disk_total_space() para calcular porcentajes de uso, formatee el valor de bytes en bruto para mostrarlo y compruebe siempre si se devuelve false. Para obtener más información sobre las funciones integradas de PHP, consulte el capítulo de funciones PHP.

Práctica