fread()

La función fread() lee un número determinado de bytes de un archivo abierto. A diferencia de los helpers que leen un archivo completo en una sola llamada, fread() te ofrece control preciso sobre cuánto lees a la vez — exactamente lo que necesitas para archivos grandes, datos binarios o contenido en streaming. Esta página cubre su sintaxis, valor de retorno, cómo leer un archivo en fragmentos seguros y los errores más comunes.

Sintaxis

fread(resource $stream, int $length): string|false

fread() se detiene en cuanto ocurre una de estas situaciones: se han leído $length bytes, se llega al final del archivo (EOF), hay un paquete disponible (para streams de red) o se han leído 8192 bytes después de que el buffer del stream se llenó (para archivos no regulares). Devuelve los bytes leídos como un string, o false en caso de error.

fread() es segura con datos binarios — lee los bytes exactamente como son, por lo que funciona con imágenes, PDFs y otros archivos que no son texto plano.

Leer un archivo completo

El uso más sencillo es leer un archivo entero en una sola llamada, pasando su tamaño como $length:

<?php

$filename = 'myfile.txt';
$file = fopen($filename, 'r');

if ($file) {
    $data = fread($file, filesize($filename));
    echo $data;
    fclose($file);
}

Aquí fopen() abre el archivo en modo solo lectura ('r'), filesize() indica cuántos bytes contiene el archivo y fread() lee exactamente esa cantidad. Siempre combina fopen() con fclose() para liberar el manejador de archivo.

Para leer un archivo completo cuando no necesitas un manejador, file_get_contents() es una alternativa de una sola línea. Usa fread() cuando necesites controlar el tamaño de lectura o procesar el archivo de forma incremental.

Leer un archivo en fragmentos

Para archivos grandes no debes cargar todo en memoria de una vez. Lee un fragmento de tamaño fijo en cada iteración y detente al final del archivo usando feof():

<?php

$file = fopen('large.log', 'r');

if ($file) {
    while (!feof($file)) {
        $chunk = fread($file, 1024); // read up to 1 KB at a time
        echo $chunk;
    }
    fclose($file);
}

Esto mantiene el uso de memoria constante independientemente del tamaño del archivo, ya que solo un fragmento de 1 KB reside en memoria a la vez. Aumenta el tamaño del fragmento (por ejemplo 8192) para intercambiar más memoria por menos llamadas de lectura.

Valor de retorno y manejo de errores

fread() devuelve un string con los bytes leídos. Al final del archivo devuelve un string vacío "", y en caso de fallo devuelve false. Como "" y false son ambos falsy, usa una comprobación estricta cuando necesites distinguirlos:

<?php

$file = fopen('data.bin', 'rb');

if ($file === false) {
    exit('Could not open the file.');
}

$bytes = fread($file, 16);

if ($bytes === false) {
    echo 'Read failed.';
} else {
    echo 'Read ' . strlen($bytes) . " bytes.\n";
}

fclose($file);

Nota el modo 'rb': en Windows, abrir en modo binario (b) evita la traducción de saltos de línea que podría corromper datos binarios. Es inofensivo en otras plataformas, por lo que es una buena práctica para cualquier archivo que no sea texto.

Errores comunes

• $length es un máximo, no una garantía. Una sola llamada a fread() puede devolver menos bytes de los solicitados (por ejemplo, cerca del EOF o en un stream de red). Para leer una cantidad exacta, itera hasta acumular suficientes bytes o alcanzar el EOF.
• El archivo debe estar abierto en un modo legible. Modos como 'w' abren solo para escritura; usa 'r', 'r+', 'a+', etc. Consulta fopen() para la lista completa de modos.
• No olvides fclose(). Los manejadores sin cerrar pueden agotar los descriptores de archivo disponibles en scripts de larga ejecución.
• ¿Leer líneas? Si quieres leer una línea a la vez en lugar de un número de bytes, fgets() es la herramienta adecuada.

Funciones relacionadas

• fopen() — abre un archivo y obtiene el puntero que necesita fread().
• fwrite() — la contraparte que escribe bytes en un archivo.
• fgets() — lee una sola línea en lugar de un número de bytes.
• feof() — comprueba el final del archivo al iterar.
• file-get-contents() — lee un archivo completo en una sola llamada.
• fclose() — cierra el manejador de archivo cuando terminas.

Conclusión

fread() es la herramienta de PHP para leer un número preciso de bytes de un archivo abierto. Úsala con filesize() para obtener un archivo completo, o combínala con feof() para transmitir archivos grandes en fragmentos eficientes en memoria. Recuerda que $length es un límite superior, abre los archivos binarios con el flag b y siempre cierra el manejador con fclose().

Práctica