md5_file()

La función md5_file() de PHP lee un archivo y devuelve el hash MD5 de su contenido como una cadena hexadecimal de 32 caracteres. A diferencia de md5(), que genera el hash de una cadena que ya tienes en memoria, md5_file() transmite el archivo desde el disco — de modo que puedes obtener la huella digital de un archivo de cualquier tamaño sin necesidad de cargarlo completamente en una variable primero.

Esta página cubre la sintaxis, los dos modos de salida, los usos prácticos para los que md5_file() es adecuada (verificación de integridad, detección de cambios, deduplicación), los problemas a tener en cuenta y los casos donde MD5 no es la herramienta correcta.

Sintaxis

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

Valor de retorno: el hash MD5 en caso de éxito, o false si el archivo no se puede leer. (Antes de PHP 8.0, el segundo argumento se llamaba $raw_output.)

Ejemplo básico

El hash se calcula a partir de los bytes del archivo, por lo que un archivo que contiene exactamente el texto Hello, World! (sin salto de línea al final) siempre produce el mismo resumen:

Salida:

65a8e27d8879283831b664bd8b7f0ad4

Dado que MD5 es determinista, generar el hash del mismo contenido en cualquier lugar — en cualquier máquina, en cualquier lenguaje — produce este valor idéntico. Esa propiedad es lo que lo hace útil para los casos que se describen a continuación.

Verificar la integridad de un archivo

El uso más común es confirmar que un archivo descargado coincide con un checksum publicado. Compara el hash que calculas con el valor esperado usando hash_equals() (una comparación resistente a ataques de temporización) en lugar 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.";
}
?>

Detectar cambios y deduplicar

Almacenar el hash de un archivo te permite detectar de forma económica si ha cambiado más adelante: vuelve a calcularlo y compáralo con el valor almacenado. Dos archivos con el mismo hash son (con una probabilidad abrumadora) idénticos byte a byte, lo que hace que md5_file() sea útil para detectar duplicados:

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

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

Salida binaria sin procesar

Pasa true como segundo argumento para obtener los 16 bytes sin procesar en lugar de los 32 caracteres hexadecimales. Esto es útil cuando necesitas almacenar el hash de forma compacta en una columna de base de datos de ancho fijo BINARY(16):

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

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

Manejo de errores

Si la ruta no existe o no es legible, md5_file() devuelve false y emite una advertencia. Siempre verifica si el archivo falta antes de calcular el hash para poder reportar un error claro:

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

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

Cuándo no usar MD5

MD5 es rápido y adecuado para tareas no relacionadas con la seguridad, como la detección de cambios, claves de caché y deduplicación. Está roto para propósitos de seguridad: los atacantes pueden crear dos archivos diferentes con el mismo hash MD5 (una colisión). No lo uses para:

• almacenar contraseñas (usa password_hash()),
• proteger contra la manipulación maliciosa de un archivo.

Para huellas digitales resistentes a manipulaciones, prefiere un resumen de la familia SHA-2 mediante hash_file():

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

Funciones relacionadas

• md5() — genera el hash de una cadena en lugar de un archivo.
• sha1_file() — hash SHA-1 del contenido de un archivo.
• crc32() — checksum rápido de 32 bits para detección de errores.
• file_get_contents() — lee un archivo completo en una cadena.

Resumen

md5_file() devuelve el resumen MD5 del contenido de un archivo — una cadena hexadecimal por defecto, o binario sin procesar con $binary = true. Es ideal para la verificación de integridad, la detección de cambios y la deduplicación, pero nunca debe usarse para trabajos sensibles a la seguridad, donde un hash SHA-2 mediante hash_file() es la elección correcta.

Práctica