diskfreespace()

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

La función diskfreespace() devuelve el número de bytes de espacio libre disponibles en el sistema de archivos o partición de disco que contiene un directorio dado. Es útil cuando necesitas verificar la capacidad antes de escribir archivos grandes, construir paneles de monitoreo del servidor o advertir a un administrador de que el almacenamiento está llegando a su límite.

diskfreespace() es simplemente un alias de disk_free_space() — ambos nombres llaman exactamente la misma implementación en C y se comportan de forma idéntica. La versión con guion bajo es el nombre canónico en el manual de PHP; la versión sin guion bajo existe por compatibilidad con versiones anteriores. El código nuevo debería preferir disk_free_space(), aunque seguirás encontrando diskfreespace() en bases de código más antiguas.

Este capítulo cubre la sintaxis, el único argumento que acepta, qué devuelve, ejemplos ejecutables y los errores comunes a evitar.

Sintaxis

diskfreespace(string $directory): float|false

La función acepta un argumento obligatorio y devuelve el espacio libre como número de bytes en punto flotante. Se usa un float (en lugar de un int) porque los discos modernos pueden almacenar muchos más bytes de los que un entero de 32 bits puede representar. En caso de fallo, devuelve false.

Parámetro

• $directory (string, obligatorio) — Un directorio en el sistema de archivos que deseas inspeccionar (por ejemplo "/", "C:" o "." para el directorio actual). PHP mide la partición en la que reside ese directorio, no el tamaño del directorio en sí. La ruta debe ser un directorio; pasar un archivo regular genera una advertencia y devuelve false.

Valor de retorno

• En caso de éxito: un float — el número de bytes libres en la partición.
• En caso de fallo (la ruta no existe, no es un directorio o no tiene permisos de lectura): false, más un E_WARNING.

Ejemplos

Ejemplo 1: Espacio libre en la partición actual

La llamada más segura y portable usa "." (el directorio actual), que funciona en todos los sistemas operativos:

<?php
$bytes = diskfreespace(".");
echo $bytes, " bytes free\n";

La salida es un conteo de bytes sin formato, como por ejemplo:

123456789012 bytes free

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

Los bytes sin procesar son difíciles de leer. Este helper convierte el valor a KB / MB / GB / TB:

<?php
function humanSize(float $bytes): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];
    $i = 0;
    while ($bytes >= 1024 && $i < count($units) - 1) {
        $bytes /= 1024;
        $i++;
    }
    return round($bytes, 2) . ' ' . $units[$i];
}

echo humanSize(123456789012); // 114.98 GB

Salida:

114.98 GB

Ejemplo 3: Verificar una ruta específica y manejar fallos

Siempre comprueba si el resultado es false antes de usarlo, porque la ruta puede ser inválida:

<?php
$path = "/no/such/directory";
$free = @diskfreespace($path);

if ($free === false) {
    echo "Could not read free space for $path";
} else {
    echo "Free: $free bytes";
}

El @ suprime la advertencia para que puedas manejar el error de forma elegante con tu propio mensaje.

Errores comunes a evitar

• Mide la partición, no la carpeta. Llamar a diskfreespace("/var/www") informa el espacio libre en el disco donde reside /var/www, no cuánto usa esa carpeta en particular.
• Pasa un directorio, no un archivo. Una ruta de archivo (p. ej. "/etc/hosts") devuelve false y emite una advertencia.
• Rutas en Windows. Usa una letra de unidad como "C:" en lugar de una ruta estilo Unix.
• Espacio libre frente a espacio utilizable. En algunos sistemas de archivos, una parte del espacio "libre" está reservada para el usuario root, por lo que el valor puede diferir ligeramente del que un proceso no root puede usar realmente.

Funciones relacionadas

• disk_free_space() — el nombre canónico de esta misma función.
• disk_total_space() — capacidad total de la partición; combínalo con esta función para calcular el porcentaje usado.
• filesize() — tamaño de un archivo individual en bytes.

Conclusión

diskfreespace() devuelve los bytes libres en la partición que contiene un directorio dado y es un alias de disk_free_space(). Úsala para monitorear el almacenamiento y protegerte contra escrituras que desborden el disco, verifica siempre si el valor de retorno es false, y combínala con disk_total_space() cuando necesites el porcentaje de espacio restante.

Práctica