fprint()

A função PHP fprintf() escreve uma string formatada em um arquivo aberto (stream). Pense nela como printf() — que imprime no navegador/saída — mas com o destino redirecionado para um identificador de arquivo. É a escolha natural quando você deseja texto limpo, alinhado e previsível em um arquivo de log ou relatório gerado, em vez de construir strings manualmente com concatenação.

Esta página cobre a sintaxe, os especificadores de formato mais utilizados, dois exemplos completos executáveis e as funções relacionadas que você pode usar como alternativa.

Sintaxe

int fprintf ( resource $handle , string $format [, mixed ...$args ] )

A função retorna o número de bytes escritos, ou false em caso de falha. Observe que o valor de retorno é o comprimento da string escrita, não o número de argumentos — útil quando você precisa rastrear quanto dado foi registrado.

Especificadores de formato

O poder do fprintf() está na string $format. Cada % introduz um marcador:

Os mesmos especificadores funcionam em printf() e sprintf(), portanto, uma vez que você os aprenda aqui, eles se aplicam em todo lugar.

Gravando um relatório

Aqui está um exemplo completo que escreve um pequeno relatório em um arquivo.

<?php
$file = fopen("report.txt", "w");
if ($file === false) {
    die("Failed to open file");
}
$name = "John";
$age = 30;
$income = 50000;
// \$ prints a literal dollar sign; %.2f rounds the float to 2 decimals
$bytes = fprintf($file, "Name: %s\nAge: %d\nIncome: \$%.2f", $name, $age, $income / 12);
fclose($file);

echo "$bytes bytes written"; // 35 bytes written
?>

Abrimos report.txt para escrita ("w") e verificamos se fopen() não falhou. Em seguida, fprintf() substitui cada variável na string de formato: %s para o nome, %d para a idade e \$%.2f para a renda mensal (um $ literal seguido de um float arredondado para duas casas decimais). Sempre chame fclose() quando terminar para que o buffer seja liberado e o identificador seja fechado.

O arquivo report.txt resultante contém:

Name: John
Age: 30
Income: $4166.67

50000 / 12 é 4166.6667, que %.2f arredonda para 4166.67.

Adicionando dados a um arquivo de log

Um uso muito comum é adicionar uma linha formatada a um log. Abra o arquivo no modo de acréscimo ("a") para que cada chamada adicione uma nova linha em vez de sobrescrever o conteúdo anterior:

<?php
$file = fopen("error.log", "a");
if ($file === false) {
    die("Failed to open file");
}
$error_code = 404;
$date = date("Y-m-d H:i:s");
$ip_address = $_SERVER['REMOTE_ADDR'];
fprintf($file, "[%s] Error %d from IP address %s\n", $date, $error_code, $ip_address);
fclose($file);
?>

Como o arquivo é aberto com "a", cada execução acrescenta uma nova linha; nada que já esteja em error.log é perdido. O \n no final da string de formato coloca cada entrada em sua própria linha. Uma linha típica acrescentada tem a seguinte aparência:

[2023-03-15 15:30:00] Error 404 from IP address 192.168.0.1

fprintf() vs. funções relacionadas

Escolher a ferramenta certa mantém seu código claro:

• printf() — mesma formatação, mas escreve na saída padrão (navegador/CLI) em vez de um arquivo.
• sprintf() — retorna a string formatada em vez de escrevê-la em algum lugar, para que você possa armazená-la ou reutilizá-la.
• fwrite() — escreve bytes brutos em um arquivo sem formatação; use quando não precisar de marcadores %.
• vfprintf() — como fprintf(), mas recebe os argumentos como um único array em vez de uma lista variádica.

Armadilhas comuns

• Especificadores e argumentos incompatíveis. %d em uma string não numérica produz 0; passar menos argumentos do que marcadores aciona um aviso.
• Esquecer de escapar %. Para imprimir um sinal de porcentagem literal, use %%, não %.
• Esquecer fclose(). Os dados em buffer podem não ser gravados no disco até que o identificador seja fechado (ou o script termine).
• O modo de abertura importa. "w" trunca o arquivo; "a" acrescenta dados. Escolha deliberadamente.

Prática