fgetc()

Introdução à Função fgetc() do PHP

A função fgetc() do PHP lê exatamente um caractere de um arquivo aberto e avança o ponteiro do arquivo um byte para frente. O nome significa "file get character" (obter caractere do arquivo). Cada chamada retorna o próximo caractere, portanto, chamando-a repetidamente é possível percorrer um arquivo um caractere por vez.

Você recorrerá a fgetc() quando precisar de controle detalhado, caractere por caractere — por exemplo, ao construir um pequeno parser, contar caracteres específicos ou parar no momento em que encontrar um byte específico. Para a maioria das leituras de arquivos do dia a dia, a leitura por linha com fgets() ou a leitura completa do arquivo com fread()/file_get_contents() são mais rápidas e simples, pois cada chamada a fgetc() carrega o overhead de uma chamada de função. Saber quando não utilizá-la é tão importante quanto saber como fazê-lo.

Esta página aborda a sintaxe, os parâmetros, o valor de retorno, exemplos executáveis e as armadilhas comuns (especialmente o problema do fim de arquivo com "0").

Sintaxe

fgetc(resource $stream): string|false

A função recebe um único argumento e retorna o caractere lido ou false.

Parâmetros

O tipo resource permanece totalmente suportado no PHP 8+. Nenhuma alteração é necessária para compatibilidade com versões modernas.

Valores de Retorno

• Em caso de sucesso, retorna uma string contendo um único caractere lido do arquivo.
• Retorna false quando o fim do arquivo (EOF) é atingido ou em caso de erro.

Exemplos

Exemplo 1: Ler um único caractere de um arquivo

Isso lê apenas o primeiro caractere do arquivo. Sempre verifique se fopen() foi bem-sucedido antes de usar o handle e chame fclose() quando terminar.

<?php

$fileHandle = fopen('example.txt', 'r');
if ($fileHandle) {
    echo fgetc($fileHandle); // prints the first character
    fclose($fileHandle);
}

Exemplo 2: Ler um arquivo inteiro caractere por caractere

Para ler o arquivo inteiro, chame fgetc() em um loop e pare quando retornar false (EOF).

<?php

$fileHandle = fopen('example.txt', 'r');
if ($fileHandle) {
    while (($char = fgetc($fileHandle)) !== false) {
        echo $char;
    }
    fclose($fileHandle);
}

Isso imprime todos os caracteres do arquivo até o EOF.

Por que !== false é importante (a armadilha do "0")

Um bug muito comum é escrever o loop com uma comparação fraca:

// BUGGED: stops early on the first "0" or "" it reads
while ($char = fgetc($fileHandle)) {
    echo $char;
}

O PHP trata as strings "0" e "" como falsy. Se o seu arquivo contiver um caractere 0, esse loop encerrará ali em vez de no EOF. Sempre use a comparação estrita de identidade !== false para que apenas o valor real de EOF interrompa o loop. A mesma regra se aplica a fgets() e fread().

Exemplo 3: Contar ocorrências de um caractere

Como fgetc() fornece um caractere por vez, é conveniente para contagens em streaming sem carregar o arquivo inteiro na memória:

<?php

$fileHandle = fopen('example.txt', 'r');
$vowels = 0;
if ($fileHandle) {
    while (($char = fgetc($fileHandle)) !== false) {
        if (str_contains('aeiouAEIOU', $char)) {
            $vowels++;
        }
    }
    fclose($fileHandle);
    echo "Vowels: $vowels";
}

fgetc() vs fgets() vs fread()

Para arquivos binários, prefira fread() — usar um loop com fgetc() funciona, mas é muito mais lento por byte.

Notas e Armadilhas

• fgetc() funciona em streams seguros para binários: retorna um byte mesmo para caracteres não textuais. Caracteres UTF-8 multibyte abrangem vários bytes, portanto uma única chamada a fgetc() pode retornar apenas parte de tal caractere.
• Abra o arquivo com o modo correto ('r', 'rb', etc.) usando fopen() e lembre-se de fechá-lo com fclose().
• Você também pode testar o fim do arquivo explicitamente com feof(), embora comparar fgetc() contra false geralmente seja suficiente.

Conclusão

fgetc() lê um caractere por vez de um ponteiro de arquivo aberto e retorna false no fim do arquivo, o que a torna ideal para parsing e contagem no nível de caractere. Lembre-se apenas dos dois pontos essenciais: passe um resource aberto de fopen() e encerre seu loop de leitura com a verificação estrita !== false para que um 0 literal nunca o interrompa prematuramente. Para trabalhos baseados em linhas ou blocos, prefira fgets() ou fread().

Para saber mais sobre como trabalhar com arquivos em PHP, consulte o guia Manipulação de Arquivos PHP.

Prática