fread()

A função fread() lê um número determinado de bytes de um arquivo aberto. Ao contrário de helpers que lêem um arquivo inteiro em uma única chamada, o fread() oferece controle preciso sobre quanto você lê por vez — exatamente o que você precisa para arquivos grandes, dados binários ou conteúdo em streaming. Esta página aborda sua sintaxe, valor de retorno, como ler um arquivo em partes seguras e as armadilhas mais comuns.

Sintaxe

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

fread() para assim que uma dessas condições ocorre: $length bytes foram lidos, o fim do arquivo (EOF) é atingido, um pacote fica disponível (para streams de rede) ou 8192 bytes foram lidos após o buffer do stream ser preenchido (para arquivos não regulares). Retorna os bytes lidos como uma string, ou false em caso de falha.

fread() é seguro para binários — lê os bytes exatamente como estão, funcionando para imagens, PDFs e outros arquivos não textuais, não apenas texto simples.

Lendo um arquivo inteiro

O uso mais simples é ler um arquivo completo em uma única chamada, passando seu tamanho como $length:

<?php

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

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

Aqui fopen() abre o arquivo em modo somente leitura ('r'), filesize() informa quantos bytes o arquivo contém, e fread() lê exatamente esse número. Sempre combine fopen() com fclose() para liberar o handle do arquivo.

Para ler um arquivo inteiro quando você não precisa de um handle, file_get_contents() é uma alternativa de uma linha. Use fread() quando precisar controlar o tamanho da leitura ou processar o arquivo de forma incremental.

Lendo um arquivo em partes

Para arquivos grandes, você não deve carregar tudo na memória de uma vez. Leia uma parte de tamanho fixo por iteração e pare no fim do arquivo 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);
}

Isso mantém o uso de memória constante independentemente do tamanho do arquivo, pois apenas um pedaço de 1 KB fica na memória por vez. Aumente o tamanho da parte (por exemplo, 8192) para trocar mais memória por menos chamadas de leitura.

Valor de retorno e tratamento de erros

fread() retorna uma string com os bytes lidos. No fim do arquivo, retorna uma string vazia "", e em caso de falha retorna false. Como "" e false são ambos falsy, use uma verificação estrita quando precisar diferenciá-los:

<?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);

Observe o modo 'rb': no Windows, abrir em modo binário (b) evita a tradução de terminação de linha que corromperia dados binários. Não causa problemas em outras plataformas, portanto é uma boa prática para qualquer arquivo não textual.

Armadilhas comuns

• $length é um máximo, não uma garantia. Um único fread() pode retornar menos bytes do que o solicitado (por exemplo, perto do EOF ou em um stream de rede). Para ler uma quantidade exata, faça um loop até coletar o suficiente ou atingir o EOF.
• O arquivo deve ser aberto em modo legível. Modos como 'w' abrem apenas para escrita; use 'r', 'r+', 'a+', etc. Consulte fopen() para a lista completa de modos.
• Não esqueça o fclose(). Vazar handles pode esgotar os descritores de arquivo disponíveis em scripts de longa execução.
• Quer ler linhas? Se você quiser uma linha por vez em vez de uma contagem de bytes, fgets() é a ferramenta mais adequada.

Funções relacionadas

• fopen() — abre um arquivo e obtém o ponteiro que fread() precisa.
• fwrite() — o equivalente que escreve bytes em um arquivo.
• fgets() — lê uma única linha em vez de uma contagem de bytes.
• feof() — testa o fim do arquivo ao fazer loop.
• file-get-contents() — lê um arquivo inteiro em uma única chamada.
• fclose() — fecha o handle do arquivo quando terminar.

Conclusão

fread() é a ferramenta do PHP para ler um número preciso de bytes de um arquivo aberto. Use-a com filesize() para obter um arquivo inteiro, ou faça loop com feof() para transmitir arquivos grandes em partes que economizam memória. Lembre-se de que $length é um limite superior, abra arquivos binários com o flag b e sempre feche o handle com fclose().

Prática