filesize()

Cos'è la funzione filesize()?

filesize() è una funzione PHP integrata che restituisce la dimensione di un file, misurata in byte, come numero intero. È il metodo standard per scoprire quanto spazio su disco occupa un file prima di scaricarlo, visualizzarlo, convalidare un upload o decidere se caricarlo in memoria.

Questa pagina tratta la sintassi, il significato del valore restituito, l'importante insidia legata ai risultati memorizzati nella cache, come trasformare i byte grezzi in una stringa leggibile dall'utente e come gestire in modo sicuro i file mancanti o illeggibili.

Sintassi

filesize(string $filename): int|false

• $filename — Percorso del file. Può essere un percorso relativo, un percorso assoluto o un wrapper URL (ad es. http://, ftp://) dove il protocollo supporta la segnalazione della dimensione.
• Valore restituito — La dimensione del file in byte come numero intero, oppure false in caso di errore (ad esempio, il file non esiste o non si dispone dei permessi per accedervi).

Poiché la dimensione è in byte, un file segnalato come 2048 è 2 KB, mentre 1048576 è esattamente 1 MB.

Un Esempio Base

L'esempio seguente crea un piccolo file temporaneo, vi scrive una stringa nota e ne riporta la dimensione. Creare il file prima rende l'esempio completamente autonomo ed eseguibile:

<?php

$filename = 'example.txt';
file_put_contents($filename, 'Hello, world!'); // 13 bytes

$bytes = filesize($filename);
echo "The file '$filename' is $bytes bytes.";
// The file 'example.txt' is 13 bytes.

La stringa Hello, world! è composta da 13 caratteri ASCII, quindi il file è esattamente 13 byte. Per i file di testo in codifica a byte singolo, il conteggio dei byte equivale al conteggio dei caratteri; i caratteri multi-byte (UTF-8) contano come più di un byte.

filesize() opera sul file così com'è su disco. Non conta i byte in memoria, e per i link simbolici riporta la dimensione del file di destinazione.

Gestione di un File Mancante o Illeggibile

Se il file non esiste, filesize() restituisce false e genera un avviso. Verificare sempre che il file esista prima, in modo da poter gestire l'errore con eleganza:

<?php

$filename = 'does-not-exist.txt';

if (file_exists($filename)) {
    echo filesize($filename) . " bytes";
} else {
    echo "File not found.";
}
// File not found.

Poiché false è vagamente uguale a 0, non scrivere mai if (filesize($f) == 0) per verificare se un file è vuoto senza prima confermare che il file esista — un file mancante e un file vuoto sembrerebbero identici. Vedere file_exists() per il controllo preventivo sicuro.

L'Insidia della Cache (clearstatcache)

PHP memorizza nella cache il risultato delle funzioni del filesystem come filesize(), filemtime() e stat() per migliorare le prestazioni. Se un file cambia durante la stessa esecuzione dello script, filesize() potrebbe restituire la dimensione precedente. Chiamare clearstatcache() per forzare una lettura aggiornata:

<?php

$filename = 'log.txt';
file_put_contents($filename, 'first');
echo filesize($filename) . "\n"; // 5

file_put_contents($filename, 'first-second');
clearstatcache(); // discard the cached size
echo filesize($filename) . "\n"; // 12

Senza la chiamata a clearstatcache(), il secondo echo potrebbe ancora stampare 5. Questa è la causa più comune di risultati "errati" di filesize().

Conversione dei Byte in una Dimensione Leggibile

I conteggi di byte grezzi sono difficili da leggere. Un piccolo helper li converte in KB, MB, GB e così via:

<?php

function humanFilesize(int $bytes, int $decimals = 2): string
{
    $units = ['B', 'KB', 'MB', 'GB', 'TB'];
    $factor = (int) floor((strlen((string) $bytes) - 1) / 3);
    $value = $bytes / (1024 ** $factor);

    return number_format($value, $decimals) . ' ' . $units[$factor];
}

echo humanFilesize(13);        // 13.00 B
echo "\n";
echo humanFilesize(2048);      // 2.00 KB
echo "\n";
echo humanFilesize(1048576);   // 1.00 MB

Qui number_format() gestisce i decimali e 1024 ** $factor divide per la potenza corretta di 1024. Sostituire con round() se si preferisce un risultato numerico senza separatori delle migliaia.

Quando Usare filesize()?

• Convalidare gli upload — rifiutare i file più grandi di un limite prima di salvarli (abbinarlo a is_uploaded_file()).
• Impostare gli header di download — inviare un header Content-Length corretto in modo che i browser possano mostrare una barra di avanzamento.
• Decidere come leggere un file — per un file di grandi dimensioni, trasmetterlo in streaming con fopen()/fread() invece di caricarlo tutto con file_get_contents().
• Monitoraggio — verificare se un file di log sta crescendo come previsto.

Funzioni Correlate

• file_exists() — verificare che un file esista prima di misurarlo.
• filemtime() — ottenere la data dell'ultima modifica di un file.
• filetype() — determinare se un percorso è un file, una directory o un link.
• file_get_contents() — leggere un intero file in una stringa.

Riepilogo

filesize() restituisce la dimensione di un file in byte, oppure false in caso di errore. Verificare sempre prima che il file esista, ricordarsi di chiamare clearstatcache() quando un file cambia durante l'esecuzione dello script e convertire i byte in un'unità comprensibile con un helper quando si mostra il risultato agli utenti.

Pratica