md5_file()

A função PHP md5_file() lê um arquivo e retorna o hash MD5 de seu conteúdo como uma string hexadecimal de 32 caracteres. Diferente de md5(), que calcula o hash de uma string já carregada em memória, md5_file() lê o arquivo diretamente do disco — assim você pode calcular a impressão digital de um arquivo de qualquer tamanho sem precisar carregá-lo inteiro em uma variável primeiro.

Esta página aborda a sintaxe, os dois modos de saída, os usos práticos para os quais md5_file() é indicada (verificação de integridade, detecção de alterações, deduplicação), os pontos de atenção e os casos em que MD5 não é a ferramenta certa.

Sintaxe

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

Valor de retorno: o hash MD5 em caso de sucesso, ou false se o arquivo não puder ser lido. (Antes do PHP 8.0, o segundo argumento se chamava $raw_output.)

Exemplo básico

O hash é calculado a partir dos bytes do arquivo, portanto um arquivo contendo exatamente o texto Hello, World! (sem nova linha ao final) sempre produz o mesmo digest:

Saída:

65a8e27d8879283831b664bd8b7f0ad4

Por ser determinístico, o MD5 do mesmo conteúdo em qualquer máquina, em qualquer linguagem, sempre produz esse mesmo valor. É essa propriedade que o torna útil nos casos descritos a seguir.

Verificação de integridade de arquivos

O uso mais comum é confirmar que um arquivo baixado corresponde ao checksum publicado. Compare o hash calculado com o valor esperado usando hash_equals() (uma comparação segura contra ataques de temporização) em vez de ==:

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

Detecção de alterações e deduplicação

Armazenar o hash de um arquivo permite verificar de forma eficiente se ele foi alterado posteriormente: recalcule o hash e compare com o valor armazenado. Dois arquivos com o mesmo hash são (com probabilidade esmagadora) idênticos byte a byte, o que torna md5_file() útil para identificar duplicatas:

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

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

Saída em binário bruto

Passe true como segundo argumento para obter os 16 bytes brutos em vez de 32 caracteres hexadecimais. Isso é útil quando você precisa armazenar o hash de forma compacta em uma coluna BINARY(16) no banco de dados:

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

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

Tratamento de erros

Se o caminho não existir ou não puder ser lido, md5_file() retorna false e emite um aviso. Sempre verifique se o arquivo está acessível antes de calcular o hash para poder reportar um erro claro:

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

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

Quando não usar MD5

MD5 é rápido e adequado para tarefas sem requisitos de segurança, como detecção de alterações, chaves de cache e deduplicação. Ele é vulnerável para fins de segurança: atacantes podem criar dois arquivos diferentes com o mesmo hash MD5 (colisão). Não o utilize para:

• armazenar senhas (use password_hash()),
• proteger contra adulteração maliciosa de arquivos.

Para impressões digitais resistentes a adulteração, prefira um digest da família SHA-2 via hash_file():

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

Funções relacionadas

• md5() — calcula o hash de uma string em vez de um arquivo.
• sha1_file() — hash SHA-1 do conteúdo de um arquivo.
• crc32() — checksum de 32 bits rápido para detecção de erros.
• file_get_contents() — lê um arquivo inteiro em uma string.

Resumo

md5_file() retorna o digest MD5 do conteúdo de um arquivo — uma string hexadecimal por padrão, ou binário bruto com $binary = true. É ideal para verificação de integridade, detecção de alterações e deduplicação, mas nunca deve ser usada em contextos que exijam segurança, onde um hash SHA-2 via hash_file() é a escolha correta.

Prática