disk_free_space()

Introduzione alla funzione PHP disk_free_space()

La funzione disk_free_space() restituisce il numero di byte disponibili nel file system che contiene una determinata directory. È uno strumento fondamentale per gli amministratori di server e gli sviluppatori web che devono monitorare l'utilizzo del disco prima di scrivere upload, generare report o ruotare i log — in modo che un'applicazione possa avvisare (o rifiutare la scrittura) prima che il disco si riempia.

Un aspetto fondamentale da capire subito: il percorso passato identifica un file system, non una singola cartella. Che tu passi /, /home o /home/user/uploads, PHP individua il file system montato su cui risiede quel percorso e riporta lo spazio libero per l'intero mount. Il valore è un float perché i dischi superano facilmente il limite di un intero a 32 bit.

Questo capitolo tratta la sintassi, i parametri, il valore restituito e esempi pratici — tra cui come convertire il conteggio grezzo di byte in una dimensione leggibile e come calcolare la percentuale di disco utilizzata.

Sintassi

disk_free_space(string $directory): float|false

La funzione accetta un singolo argomento e restituisce il numero di byte liberi come float, oppure false in caso di errore (ad esempio, quando la directory non esiste). Si noti che diskfreespace() è un alias di questa funzione e si comporta in modo identico.

Parametri

La funzione disk_free_space() accetta un parametro obbligatorio:

• $directory — Un percorso string verso qualsiasi file o directory nel file system che si desidera esaminare. La funzione riporta lo spazio libero del mount che contiene questo percorso, non la dimensione della directory stessa.

Valore restituito

In caso di successo, disk_free_space() restituisce lo spazio disponibile in byte come float. In caso di errore restituisce false ed emette un avviso, quindi è sempre necessario validare il percorso o verificare il risultato prima di utilizzarlo.

Esempi

Esempio 1: Ottenere lo spazio libero su un file system

Passa la directory radice per esaminare il file system su cui è installato il sistema operativo:

<?php

$bytes = disk_free_space("/");

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

Il numero esatto dipende dalla macchina; su un disco con circa 20 GB liberi viene stampato 21474836480.

Esempio 2: Formattare il risultato come dimensione leggibile

Un conteggio grezzo di byte è difficile da leggere. Questo helper converte i byte nell'unità più vicina (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

Esempio 3: Calcolare la percentuale di disco utilizzata

Combina disk_free_space() con disk_total_space() per riportare quanto è pieno un volume:

<?php

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

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

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

Per un disco da 100 GB con 20 GB liberi viene stampato Disk usage: 80%.

Esempio 4: Proteggere una scrittura con un controllo degli errori

Poiché la funzione restituisce false per un percorso errato, verifica il risultato prima di agire:

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

Errori comuni

• Misura il mount, non la cartella. Per trovare la dimensione del contenuto di una directory, è necessario sommare le dimensioni dei file (vedi filesize()) — disk_free_space() non lo fa.
• Gestisci false. Un percorso inesistente o non leggibile restituisce false e genera un avviso. Valida l'input prima di passarlo.
• Il risultato è un float. Non confrontarlo con interi usando ===, e non supporre che rientri in un int a 32 bit — i dischi di grandi dimensioni causano overflow.
• Le restrizioni di open_basedir possono far fallire la chiamata sull'hosting condiviso se il percorso si trova al di fuori delle directory consentite.

Conclusione

La funzione disk_free_space() riporta i byte disponibili nel file system contenente un determinato percorso — essenziale per monitorare lo storage e proteggere le scritture da un disco pieno. Abbinala a disk_total_space() per calcolare le percentuali di utilizzo, formatta il valore grezzo in byte per la visualizzazione e verifica sempre la presenza di un valore false restituito. Per ulteriori informazioni sulle funzioni built-in di PHP, consulta il capitolo PHP functions.

Esercizio