fprintf()

Introdução

A função fprintf() escreve uma string formatada em um stream — um arquivo, php://stdout, php://stderr ou qualquer outro recurso de stream aberto — e preenche seus marcadores a partir de uma lista de argumentos separados. O f no nome representa file: diferente de printf(), que imprime diretamente na saída, fprintf() envia seu resultado para um stream escolhido por você.

Ela é o membro da família printf responsável por gravar em streams. Comparada com vfprintf(), ambas realizam exatamente a mesma tarefa, mas recebem seus valores de forma diferente: fprintf() recebe cada valor como um argumento individual, enquanto vfprintf() recebe um único array. Use fprintf() quando você tiver alguns valores separados para gravar em um arquivo ou no console.

Este capítulo abrange a sintaxe, os especificadores de formato, exemplos executáveis, como ela se compara com as funções relacionadas e armadilhas comuns.

Sintaxe

fprintf(resource $stream, string $format, mixed ...$values): int

Ela retorna o número de caracteres escritos. No PHP moderno, uma chamada mal formada gera um erro em vez de retornar false, portanto raramente é necessário testar o valor de retorno em busca de falhas.

Especificadores de formato

A string $format combina texto literal com marcadores que começam com %. Os especificadores mais comuns são:

Entre o % e a letra de tipo você pode adicionar largura, preenchimento e precisão — por exemplo, %05d (preenche um inteiro com 5 dígitos usando zeros) ou %.2f (duas casas decimais). Um % literal deve ser escrito como %%.

Exemplo: gravando na saída padrão

Abrir o stream php://stdout permite ver o resultado imediatamente, o que facilita experimentar o fprintf():

<?php

$out = fopen("php://stdout", "w");

fprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", "John", 30, 1234.5);

fclose($out);

Saída:

Name: John | Age: 30 | Balance: 1234.50

Os três argumentos preenchem %s, %d e %.2f em ordem: a string é impressa como está, %d descarta a parte decimal de um inteiro e %.2f formata o float com exatamente duas casas decimais.

Exemplo: gravando em um arquivo

O caso de uso clássico é gravar linhas formatadas e alinhadas em um arquivo — por exemplo, um pequeno log:

<?php

$log = fopen("app.log", "a");

fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "INFO", "Server started");
fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "ERROR", "Disk full");

fclose($log);

echo file_get_contents("app.log");

Saída:

[2026-07-02] INFO  Server started
[2026-07-02] ERROR Disk full

%-5s alinha o nível à esquerda em uma coluna de 5 caracteres, de modo que as mensagens comecem sempre na mesma posição, independentemente de o nível ser INFO ou ERROR. Abrir o arquivo com o modo "a" (acréscimo) adiciona cada linha sem truncar o que já está lá. Cada chamada de fprintf() grava uma linha, recebendo seus valores como argumentos separados.

fprintf() vs printf() vs vfprintf()

Estas três funções compartilham exatamente as mesmas regras de string de formato e diferem apenas em para onde o resultado vai e como os valores são passados:

Portanto, fprintf() é printf() gravando em um stream em vez de na saída, e é vfprintf() com argumentos separados em vez de um array:

// Argumentos separados → gravados em $stream
fprintf($stream, "%s is %d", $name, $age);

// Os mesmos valores como um array → gravados em $stream
vfprintf($stream, "%s is %d", [$name, $age]);

Se você só quiser a string formatada de volta em vez de gravá-la em algum lugar, use sprintf(). Um idioma comum de fprintf() em scripts de linha de comando é gravar diagnósticos no stream de erro, mantendo-os separados da saída normal:

<?php

fprintf(STDERR, "Error: %s (code %d)\n", "connection refused", 111);

STDERR é uma constante de stream predefinida disponível para scripts PHP CLI, então você não precisa abri-la com fopen() antes.

Armadilhas comuns

• O stream vem primeiro. O recurso de stream é o primeiro argumento; a string de formato é o segundo. Passar o formato primeiro (como em printf()) é o erro mais comum ao alternar entre as duas.
• O stream deve ser gravável. Abrir um arquivo com "r" (modo de leitura) e passá-lo para fprintf() falha — use um modo gravável, como "w" (truncar) ou "a" (acréscimo).
• Ela grava, não retorna texto. O valor de retorno é a contagem de caracteres, não a string formatada — uma confusão frequente com sprintf().
• Poucos argumentos geram um erro. Fornecer menos valores do que o formato tem especificadores lança um ArgumentCountError no PHP 8+; valores extras são simplesmente ignorados.
• Escape sinais de porcentagem literais como %%, caso contrário o PHP tentará ler o próximo caractere como um especificador.

Conclusão

fprintf() formata uma string e a grava em um stream, recebendo seus valores como argumentos separados. É a ferramenta ideal quando você quer uma saída precisa e colunar enviada para um arquivo ou para o console — linhas de log, relatórios ou diagnósticos de CLI em php://stderr. Para as variantes relacionadas, veja printf() (imprime na saída), sprintf() (retorna uma string) e vfprintf() (mesmo destino, mas recebe um array de valores).

Prática