fgets()

A função fgets() lê uma linha por vez a partir de um handle de arquivo aberto. É a forma padrão de processar arquivos de texto em PHP sem carregar o arquivo inteiro na memória — o que importa quando o arquivo é grande o suficiente para que lê-lo de uma vez (com file_get_contents() ou fread()) seria custoso ou impossível.

Esta página aborda a sintaxe, o que fgets() retorna, o laço de leitura correto, problemas comuns e como ela se relaciona com as outras funções de leitura de arquivo.

O que é a função fgets()?

fgets() lê a partir da posição atual de um handle de arquivo aberto até — e incluindo — o próximo caractere de nova linha (\n), e retorna esse texto como uma string. Em seguida, avança o ponteiro do arquivo para que a próxima chamada leia a linha seguinte.

Não está limitada a arquivos em disco: qualquer stream aberto com fopen() funciona, incluindo php://stdin para leitura de entrada do teclado e URLs remotas.

Sintaxe

fgets(resource $stream, ?int $length = null): string|false

• $stream — um ponteiro de arquivo retornado por fopen() (ou outra função de stream). Deve ainda estar aberto.
• $length (opcional) — lê no máximo $length - 1 bytes. A leitura para quando uma nova linha é encontrada, o fim do arquivo é atingido, ou $length - 1 bytes foram lidos, o que ocorrer primeiro. Omita para ler até o final da linha, independentemente do tamanho.

O que fgets() retorna

Como a nova linha é mantida, echo reproduz as quebras de linha do arquivo. Se não quiser, remova com rtrim($line, "\r\n").

O fato de fgets() retornar false no fim do arquivo é o que faz o laço de leitura abaixo funcionar — você nem precisa de feof().

Como usar fgets(): os três passos

1. Abra o arquivo com fopen() em um modo de leitura como "r".
2. Leia linha por linha com fgets().
3. Feche o handle com fclose() quando terminar.

O laço de leitura recomendado

O padrão mais limpo usa o valor de retorno false como condição do laço. A atribuição em PHP é avaliada ao valor atribuído, então while (($line = fgets($file)) !== false) lê uma linha e a testa em uma única etapa:

<?php

$file = fopen("file.txt", "r");

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

while (($line = fgets($file)) !== false) {
    echo $line;          // newline is already part of $line
}

fclose($file);

A comparação estrita !== false é importante: uma linha que contém apenas "0" é "falsy" em PHP, então um simples while ($line = fgets($file)) encerraria o laço antecipadamente nessa linha. Compare sempre com !== false.

Lendo linha por linha com feof()

Você também verá o laço escrito com feof(), que retorna true quando o fim do arquivo é atingido:

<?php

$file = fopen("file.txt", "r");

while (!feof($file)) {
    $line = fgets($file);
    if ($line === false) {
        break;          // guard against a read failure mid-loop
    }
    echo $line;
}

fclose($file);

Ambos os estilos são corretos. A versão com !== false é geralmente preferida porque feof() só se torna true após uma leitura falhar, o que pode causar uma iteração extra vazia se você não tomar cuidado.

Limitando o comprimento da linha

Passe $length para limitar quanto de uma linha longa você lê por vez. Aqui apenas os primeiros 9 bytes ($length - 1) de cada trecho são retornados:

<?php

$file = fopen("file.txt", "r");

// "Hello, world!" is read in pieces of at most 9 bytes
echo fgets($file, 10);   // "Hello, wo"
echo "\n";
echo fgets($file, 10);   // "rld!" (rest of the line)

fclose($file);

Isso é útil para proteger contra linhas muito longas, mas para arquivos de texto normais você pode omitir $length.

Lendo entrada do usuário no terminal

Como fgets() funciona em qualquer stream, é a forma clássica de ler uma linha digitada pelo usuário na linha de comando:

<?php

echo "What is your name? ";
$name = rtrim(fgets(STDIN), "\r\n");  // strip the Enter key's newline
echo "Hello, $name!\n";

STDIN é uma constante predefinida para php://stdin.

Problemas comuns

• A nova linha final está incluída. Use rtrim($line, "\r\n") ao comparar ou armazenar valores.
• Teste com !== false, não apenas com veracidade, para que linhas como "0" ou "" não encerrem o laço prematuramente.
• fgets() precisa de um handle válido e aberto. Se fopen() retornou false (arquivo ausente, permissões incorretas), passá-lo para fgets() gera um aviso. Verifique o handle primeiro.
• Não esqueça fclose(). PHP fecha os handles ao final do script, mas liberá-los explicitamente é uma boa prática, especialmente em scripts de longa execução.
• Para leituras de arquivo inteiro, prefira ferramentas mais simples. Se você não precisa de controle linha por linha, file() retorna o arquivo como um array de linhas e file_get_contents() o retorna como uma única string.

Funções relacionadas

• fopen() — abre um arquivo ou stream (necessário antes de fgets()).
• fread() — lê um número fixo de bytes, não de linhas.
• fgetc() — lê um único caractere.
• fgetcsv() — lê uma linha e a analisa como CSV.
• feof() — verifica o fim do arquivo.
• fclose() — fecha o handle.

Conclusão

fgets() lê um arquivo uma linha por vez, retornando cada linha (com a nova linha incluída) até atingir o fim do arquivo, onde retorna false. Use-a em conjunto com fopen() e fclose(), controle o laço com um teste estrito !== false e lembre-se de usar rtrim() na nova linha quando precisar do valor limpo. Para arquivos muito grandes, isso mantém o uso de memória constante, tornando fgets() a escolha ideal para processar texto de forma contínua em PHP.

Prática