vfprintf()

Introdução

A função vfprintf() escreve uma string formatada em um stream — como um arquivo ou a saída padrão — e obtém seus valores de um array em vez de uma lista de argumentos separados. O v inicial representa vector (um array de argumentos); o f representa file (ela tem como alvo um stream).

Em resumo, vfprintf() está para fprintf() assim como vsprintf() está para sprintf(): realiza a mesma formatação, mas recebe um único array em vez de cada argumento individualmente. Esta é a função indicada quando os valores já estão reunidos em um array.

Este capítulo abrange a sintaxe, os especificadores de formato, exemplos executáveis, quando escolhê-la em vez das alternativas e armadilhas comuns.

Sintaxe

vfprintf(resource $stream, string $format, array $values): int

Ela retorna o número de caracteres escritos. Na maioria das versões do PHP, uma chamada mal formada gera um erro em vez de retornar false, portanto normalmente não é necessário testar o valor de retorno em busca de falhas.

Especificadores de formato

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

Você pode adicionar largura, preenchimento e precisão entre o % e a letra de tipo — 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

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

<?php

$out    = fopen("php://stdout", "w");
$values = ["John", 30, 1234.5];

vfprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", $values);

fclose($out);

Saída:

Name: John | Age: 30 | Balance: 1234.50

Os três elementos do array 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 original é gravar linhas formatadas em um arquivo. Aqui acrescentamos três linhas extraídas de um array de registros:

<?php

$records = [
    ["Alice", 95],
    ["Bob",   82],
    ["Carol", 77],
];

$file = fopen("scores.txt", "w");

foreach ($records as $row) {
    vfprintf($file, "%-10s %3d%%\n", $row);
}

fclose($file);

echo file_get_contents("scores.txt");

Saída:

Alice       95%
Bob         82%
Carol       77%

%-10s alinha o nome à esquerda em uma coluna de 10 caracteres, %3d alinha a pontuação à direita em uma coluna de 3 caracteres e %% imprime o sinal de porcentagem literal. Como cada $row já é um array, vfprintf() o consome diretamente — sem necessidade de desempacotar os valores.

Por que usar um array? vfprintf() vs fprintf()

fprintf() recebe seus valores como argumentos separados:

fprintf($file, "%s is %d", $name, $age);

vfprintf() recebe os mesmos valores em um único array:

vfprintf($file, "%s is %d", [$name, $age]);

Use vfprintf() quando os valores já estiverem em um array — por exemplo, uma linha de banco de dados, uma linha CSV analisada ou argumentos acumulados em um loop — para não precisar desempacotá-los com o operador spread (...$row). Se você simplesmente quiser a string formatada de volta em vez de gravá-la em um stream, use vsprintf(); para imprimir diretamente na saída sem um recurso de stream, use vprintf().

Armadilhas comuns

• O array deve ter pelo menos tantos elementos quanto especificadores. Poucos valores aciona um ArgumentCountError (PHP 8+); valores extras são simplesmente ignorados.
• A ordem importa. Os elementos são consumidos posicionalmente, na ordem do array. Para referenciar um elemento específico independentemente da ordem, use marcadores numerados como %1$s e %2$d.
• Ela grava, não retorna texto. O valor de retorno é uma contagem de caracteres, não a string formatada — uma confusão frequente com vsprintf().
• O stream deve ser gravável. Abrir um arquivo com "r" (modo de leitura) e passá-lo para vfprintf() falha.

Conclusão

vfprintf() formata uma string e a grava em um stream, obtendo seus valores de um array. Ela brilha quando seus dados já estão reunidos em um array e você deseja gravá-los em um arquivo ou na saída padrão em um formato preciso e colunar. Para as variantes sem stream, consulte vsprintf() (retorna uma string) e vprintf() (imprime diretamente), e compare com fprintf() quando seus argumentos são valores separados em vez de um array.

Prática