fscanf()

O que é a Função fscanf()?

A função fscanf() lê de um arquivo aberto e analisa seu conteúdo de acordo com uma string de formato no estilo printf. Em vez de retornar uma linha de texto bruto como faz fgets(), fscanf() divide a entrada em campos tipados — strings, inteiros, floats — em uma única etapa. É a ferramenta de escolha do PHP quando um arquivo segue um layout fixo baseado em colunas e você quer cada valor já convertido para o tipo correto.

Esta página aborda a sintaxe, os especificadores de formato disponíveis, as duas formas pelas quais fscanf() pode retornar seus resultados, os erros mais comuns e como ela se compara a funções relacionadas.

Sintaxe

fscanf(resource $stream, string $format, mixed &...$vars): array|int|false

O valor de retorno depende de como você a chama:

• Com argumentos de variáveis extras → retorna o número de campos atribuídos com sucesso, ou false no fim do arquivo.
• Sem variáveis extras → retorna um array com os campos analisados em vez de escrever nas variáveis.

fscanf() avança o ponteiro do arquivo além do que consumiu, então chamadas repetidas percorrem o arquivo token por token.

Especificadores de Formato

A string de formato é o núcleo de fscanf(). Os especificadores mais comuns são:

Espaços em branco na string de formato correspondem a qualquer sequência de espaços em branco (espaços, tabulações, quebras de linha) na entrada, razão pela qual %s é delimitado por espaço em branco em vez de por linha.

Lendo um Arquivo com Variáveis

O padrão típico é: abrir o arquivo, fazer um loop enquanto fscanf() continuar retornando a contagem de campos esperada e, em seguida, fechá-lo. Suponha que data.txt contenha um registro por linha:

John Smith 30 50000.5
Jane Doe 28 62000

Você pode analisar cada linha em variáveis tipadas assim:

<?php
$file = fopen('data.txt', 'r');

if ($file === false) {
    die("Error: Could not open file.");
}

while (fscanf($file, "%s %s %d %f", $first, $last, $age, $salary) === 4) {
    echo "Name: $first $last, Age: $age, Salary: $salary\n";
}

fclose($file);
?>

Saída:

Name: John Smith, Age: 30, Salary: 50000.5
Name: Jane Doe, Age: 28, Salary: 62000

Comparar o valor de retorno com 4 (o número de campos que o formato espera) é a chave para um loop seguro: no fim do arquivo fscanf() retorna false, e em uma linha malformada retorna uma contagem menor, então o loop para de forma limpa em vez de girar para sempre.

Lendo um Arquivo em um Array

Se você omitir os argumentos de variável, fscanf() retorna cada registro analisado como um array. Isso é conveniente quando você quer coletar linhas em vez de processá-las uma variável por vez:

<?php
$file = fopen('data.txt', 'r');

while ($row = fscanf($file, "%s %s %d %f")) {
    // $row is [first, last, age, salary]
    [$first, $last, $age, $salary] = $row;
    echo "$last, $first earns $salary\n";
}

fclose($file);
?>

Saída:

Smith, John earns 50000.5
Doe, Jane earns 62000

fscanf() vs. sscanf()

fscanf() lê de um ponteiro de arquivo; sscanf() faz exatamente a mesma análise, mas em uma string que você já tem na memória. Se seus dados estiverem em uma variável em vez de um arquivo, use sscanf():

<?php
$count = sscanf("2024-06-21", "%d-%d-%d", $year, $month, $day);
echo "$count fields parsed: $year / $month / $day\n";
?>

Saída:

3 fields parsed: 2024 / 6 / 21

Erros Comuns

• %s para no espaço em branco, não no fim da linha. Um nome como New York é lido como dois campos %s, não um. Adapte o formato à forma real dos seus dados.
• Sempre verifique o valor de retorno. Fazer o loop na contagem de campos (=== 4) — e não em !feof() — mantém você protegido contra linhas incompletas e loops infinitos.
• Verifique fopen() primeiro. fscanf() precisa de um recurso válido; uma abertura com falha retorna false.
• Para dados separados por vírgula, prefira fgetcsv(). fscanf() é projetado para colunas delimitadas por espaço em branco com formato fixo, não para campos CSV com aspas.

Funções Relacionadas

• sscanf() — analisa uma string formatada em vez de um arquivo.
• fgetcsv() — lê e divide linhas CSV.
• fgets() — lê uma linha de texto bruto.
• fopen() / fclose() — abre e fecha o fluxo do arquivo.

Conclusão

fscanf() converte conteúdo de arquivo delimitado por espaço em branco em valores PHP tipados em uma única chamada. Escolha a forma com variáveis quando processar registros um por vez, ou a forma com array quando quiser coletá-los. Sempre valide o valor de retorno para controlar seu loop e mude para sscanf() para strings em memória ou fgetcsv() para CSV verdadeiro.

Prática