md5_file()

La funzione PHP md5_file() legge un file e restituisce l'hash MD5 del suo contenuto come stringa esadecimale di 32 caratteri. A differenza di md5(), che calcola l'hash di una stringa già in memoria, md5_file() legge il file direttamente dal disco — così puoi ottenere l'impronta digitale di un file di qualsiasi dimensione senza caricarlo interamente in una variabile.

Questa pagina illustra la sintassi, entrambe le modalità di output, i casi d'uso pratici in cui md5_file() è indicata (verifica dell'integrità, rilevamento delle modifiche, deduplicazione), le insidie da evitare e i contesti in cui MD5 non è lo strumento giusto.

Sintassi

md5_file(string $filename, bool $binary = false): string|false

Valore restituito: l'hash MD5 in caso di successo, oppure false se il file non può essere letto. (Prima di PHP 8.0 il secondo argomento si chiamava $raw_output.)

Esempio di base

L'hash viene calcolato dai byte del file, quindi un file che contiene esattamente il testo Hello, World! (senza newline finale) produce sempre lo stesso digest:

Output:

65a8e27d8879283831b664bd8b7f0ad4

Poiché MD5 è deterministico, calcolare l'hash dello stesso contenuto ovunque — su qualsiasi macchina, in qualsiasi linguaggio — produce questo identico valore. È questa proprietà a renderlo utile nei casi descritti di seguito.

Verifica dell'integrità del file

L'uso più comune è confermare che un file scaricato corrisponda a un checksum pubblicato. Confronta l'hash calcolato con il valore atteso usando hash_equals() (un confronto a tempo costante) anziché ==:

<?php
$expected = "65a8e27d8879283831b664bd8b7f0ad4";
$actual   = md5_file("example.txt");

if ($actual === false) {
    echo "Could not read the file.";
} elseif (hash_equals($expected, $actual)) {
    echo "File is intact.";
} else {
    echo "File is corrupted or has been modified.";
}
?>

Rilevamento delle modifiche e deduplicazione

Memorizzare l'hash di un file consente di verificare in modo economico se è cambiato in seguito: ricalcola l'hash e confrontalo con il valore salvato. Due file con lo stesso hash sono (con probabilità schiacciante) identici byte per byte, il che rende md5_file() utile per individuare i duplicati:

<?php
$a = md5_file("photo1.jpg");
$b = md5_file("photo2.jpg");

echo ($a === $b) ? "Duplicate files\n" : "Different files\n";
?>

Output binario grezzo

Passa true come secondo argomento per ottenere i 16 byte grezzi anziché 32 caratteri esadecimali. Ciò è utile quando occorre memorizzare l'hash in modo compatto in una colonna del database BINARY(16) a larghezza fissa:

<?php
$raw = md5_file("example.txt", true);

echo strlen($raw);        // 16 (bytes) instead of 32 (hex chars)
echo bin2hex($raw);       // 65a8e27d8879283831b664bd8b7f0ad4
?>

Gestione degli errori

Se il percorso è mancante o non leggibile, md5_file() restituisce false ed emette un avviso. Verifica sempre che il file esista prima di calcolarne l'hash, così da poter riportare un errore chiaro:

<?php
$filename = "example.txt";

if (!is_readable($filename)) {
    echo "File not found or not readable.";
} else {
    echo md5_file($filename);
}
?>

Quando non usare MD5

MD5 è veloce e adatto per attività non legate alla sicurezza come il rilevamento delle modifiche, le chiavi di cache e la deduplicazione. È inadatto per la sicurezza: gli aggressori possono costruire due file diversi con lo stesso hash MD5 (una collisione). Non usarlo per:

• memorizzare password (usa password_hash()),
• proteggere contro la manomissione dolosa di un file.

Per impronte digitali resistenti alla manomissione, preferisci un digest della famiglia SHA-2 tramite hash_file():

<?php
echo hash_file("sha256", "example.txt");
?>

Funzioni correlate

• md5() — calcola l'hash di una stringa anziché di un file.
• sha1_file() — hash SHA-1 del contenuto di un file.
• crc32() — checksum a 32 bit veloce per il rilevamento degli errori.
• file_get_contents() — legge l'intero contenuto di un file in una stringa.

Riepilogo

md5_file() restituisce il digest MD5 del contenuto di un file — una stringa esadecimale per impostazione predefinita, oppure binario grezzo con $binary = true. È ideale per la verifica dell'integrità, il rilevamento delle modifiche e la deduplicazione, ma non deve mai essere usata per scopi legati alla sicurezza, dove la scelta corretta è un hash SHA-2 tramite hash_file().

Esercitazione