diskfreespace()

Introduzione alla funzione PHP diskfreespace()

La funzione diskfreespace() restituisce il numero di byte di spazio libero disponibile sul file system o sulla partizione del disco che contiene una determinata directory. È utile quando è necessario verificare la capacità prima di scrivere file di grandi dimensioni, creare dashboard di monitoraggio del server o avvisare un amministratore che lo spazio di archiviazione sta per esaurirsi.

diskfreespace() è semplicemente un alias di disk_free_space() — entrambi i nomi richiamano la stessa implementazione C e si comportano in modo identico. La versione con underscore è il nome canonico nel manuale PHP; la versione senza underscore esiste per compatibilità con le versioni precedenti. Il nuovo codice dovrebbe preferire disk_free_space(), ma si incontra ancora diskfreespace() nelle basi di codice più vecchie.

Questo capitolo tratta la sintassi, l'unico argomento che la funzione accetta, cosa restituisce, esempi eseguibili e i problemi comuni.

Sintassi

diskfreespace(string $directory): float|false

La funzione accetta un argomento obbligatorio e restituisce lo spazio libero come numero in virgola mobile di byte. Viene utilizzato un float (anziché un int) perché i dischi moderni possono contenere molti più byte di quanti un intero a 32 bit possa rappresentare. In caso di errore restituisce false.

Parametro

• $directory (string, obbligatorio) — Una directory sul file system che si desidera ispezionare (ad esempio "/", "C:" o "." per la directory corrente). PHP misura la partizione su cui si trova questa directory, non le dimensioni della directory stessa. Il percorso deve essere una directory; passare un file ordinario produce un avviso e restituisce false.

Valore restituito

• In caso di successo: un float — il numero di byte liberi sulla partizione.
• In caso di errore (il percorso non esiste, non è una directory o non è leggibile): false, più un E_WARNING.

Esempi

Esempio 1: Spazio libero sulla partizione corrente

La chiamata portabile più sicura utilizza "." (la directory corrente), che funziona su ogni sistema operativo:

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

L'output è un conteggio grezzo di byte, ad esempio:

123456789012 bytes free

Esempio 2: Formattare il risultato come dimensione leggibile dall'uomo

I byte grezzi sono difficili da leggere. Questa funzione di supporto converte il valore in 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

Output:

114.98 GB

Esempio 3: Controllare un percorso specifico e gestire gli errori

Verificare sempre false prima di utilizzare il risultato, perché il percorso potrebbe non essere valido:

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

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

@ sopprime l'avviso in modo da poter gestire l'errore in modo appropriato con il proprio messaggio.

Problemi comuni

• Misura la partizione, non la cartella. Chiamare diskfreespace("/var/www") riporta lo spazio libero sul disco su cui risiede /var/www, non quanto utilizza quella singola cartella.
• Passare una directory, non un file. Un percorso di file (es. "/etc/hosts") restituisce false ed emette un avviso.
• Percorsi Windows. Utilizzare una lettera di unità come "C:" anziché un percorso in stile Unix.
• Spazio libero vs. spazio utilizzabile. Su alcuni file system una parte dello spazio "libero" è riservata all'utente root, quindi il valore potrebbe differire leggermente da quello che un processo non-root può effettivamente utilizzare.

Funzioni correlate

• disk_free_space() — il nome canonico per questa stessa funzione.
• disk_total_space() — capacità totale della partizione; combinare con questa funzione per calcolare la percentuale utilizzata.
• filesize() — dimensione di un singolo file in byte.

Conclusione

diskfreespace() restituisce i byte liberi sulla partizione che contiene una determinata directory ed è un alias di disk_free_space(). Usarla per monitorare lo spazio di archiviazione e proteggersi da scritture che causerebbero un overflow del disco, verificare sempre il valore restituito false e abbinarla a disk_total_space() quando si ha bisogno della percentuale di spazio rimanente.

Esercitazione