disk_total_space()

Introduzione alla funzione disk_total_space() di PHP

La funzione disk_total_space() in PHP restituisce la dimensione totale, in byte, del file system (o della partizione disco) che contiene una determinata directory. Non misura la dimensione della directory stessa, ma riporta la capacità del volume sottostante. Questo la rende utile per gli amministratori di server e gli sviluppatori web che desiderano monitorare la capacità del disco, costruire dashboard di archiviazione o avvisare gli utenti prima che un caricamento riempia una partizione.

Un punto chiave che spesso confonde i principianti: l'argomento è qualsiasi percorso nel volume, non il nodo dispositivo del volume. Passare /var/www, /home/user o semplicemente / restituisce sempre la dimensione totale della partizione su cui risiedono tali percorsi. Per scoprire quanto spazio è ancora disponibile, abbinare questa funzione a disk_free_space() — disk_total_space() fornisce la capacità e disk_free_space() fornisce la porzione non utilizzata.

Questa pagina illustra la sintassi, i parametri, il valore restituito e degli esempi pratici, incluso come convertire i byte grezzi in un formato leggibile dall'utente e come calcolare la percentuale di disco utilizzata.

Sintassi

La sintassi della funzione disk_total_space() è la seguente:

Sintassi di PHP disk_total_space()

disk_total_space(string $directory): float|false

Parametri

La funzione disk_total_space() accetta un parametro obbligatorio:

1. $directory: Un percorso situato nel file system che si desidera esaminare. Qualsiasi percorso valido nel volume funziona — la funzione lo risolve nella partizione a cui appartiene. Su Windows, utilizzare una lettera di unità con una barra finale, ad esempio C:\ o C:/.

Valore restituito

La funzione restituisce il numero totale di byte nel file system come float (viene usato un float perché i volumi possono superare l'intervallo di un intero a 32 bit). In caso di errore — ad esempio un percorso non valido o un errore di autorizzazione — restituisce false. Poiché una dimensione disco valida potrebbe teoricamente coincidere con un valore che PHP tratta come falsy, testare sempre il risultato con il confronto rigoroso !== false anziché un semplice controllo di veridicità.

Esempi

Ecco alcuni esempi di utilizzo della funzione disk_total_space():

Esempio 1: Recuperare la dimensione totale di un file system

L'esempio seguente recupera la dimensione totale del file system /home/:

Recuperare la dimensione totale di un file system in PHP

echo disk_total_space("/home/");

L'output di questo esempio sarà la dimensione totale del file system in byte.

Esempio 2: Recuperare la dimensione totale di una partizione disco

L'esempio seguente recupera la dimensione totale della partizione disco /dev/sda1:

Recuperare la dimensione totale di una partizione disco in PHP

echo disk_total_space("/dev/sda1");

L'output di questo esempio sarà la dimensione totale della partizione disco in byte.

Esempio 3: Convertire i byte in un formato leggibile

La funzione restituisce byte grezzi, difficili da leggere. Convertire il risultato in gigabyte e formattarlo con number_format():

Convertire la dimensione del disco in formato leggibile in PHP

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

Per un'unità che si scala automaticamente (KB, MB, GB, TB, …), utilizzare un piccolo helper:

Formattatore di byte con scala automatica 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"

Esempio 4: Calcolare la percentuale di disco utilizzata

Combinare disk_total_space() con disk_free_space() per riportare quanto è pieno un volume — utile per avvisi e script di monitoraggio:

Calcolare la percentuale di disco utilizzata 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}%";
}

Note e avvertenze

• Misura il volume, non la directory. Per ottenere la dimensione del contenuto di una cartella, sommare le dimensioni dei suoi file (ad esempio con filesize() durante l'iterazione), non con disk_total_space().
• Verificare sempre la presenza di false. Un percorso mancante, un'unità non montata o autorizzazioni insufficienti fanno fallire la chiamata; utilizzare !== false.
• open-basedir / percorsi sicuri. Se sono attive le restrizioni open_basedir, il percorso deve trovarsi all'interno di una directory consentita, altrimenti la chiamata fallisce.
• Funzione correlata. disk_free_space() (e il suo alias diskfreespace()) restituisce lo spazio disponibile nello stesso volume.

Conclusione

La funzione disk_total_space() riporta la capacità totale, in byte, del file system che contiene un determinato percorso. Abbinata a disk_free_space(), permette di costruire dashboard di archiviazione, applicare limiti di caricamento e attivare avvisi di spazio insufficiente. Ricordare i tre elementi essenziali: passare qualsiasi percorso nel volume di destinazione, trattare il valore restituito come un float e proteggersi dagli errori con un controllo rigoroso !== false.

Esercizio