vprintf()

Introdução

A função vprintf() em PHP exibe uma string formatada. Ela se comporta exatamente como printf(), exceto que os valores a substituir são fornecidos como um único array em vez de argumentos separados. O v no nome representa vector (vetor/array).

Esta página abrange a sintaxe, os especificadores de formato disponíveis, um conjunto de exemplos executáveis, as diferenças em relação às funções relacionadas e os erros comuns a evitar.

Use vprintf() quando os valores que você precisa formatar já estiverem em um array — por exemplo, uma linha de banco de dados, o resultado de explode(), ou uma lista construída dinamicamente. Espalhar esse array manualmente em printf($fmt, $row[0], $row[1], ...) é verboso e quebra no momento em que o número de campos muda; vprintf($fmt, $row) lida com qualquer quantidade de forma limpa.

Sintaxe

vprintf(string $format, array $values): int|false

• $format — uma string de modelo contendo um ou mais placeholders. Cada placeholder começa com um sinal de porcentagem (%) seguido de um especificador de conversão como s (string), d (inteiro) ou f (float).
• $values — um array cujos elementos preenchem os placeholders, em ordem. Deve conter pelo menos tantos elementos quantos forem os placeholders.

vprintf() imprime o resultado diretamente e retorna o comprimento da string de saída (um int), ou false em caso de falha. Se você precisar da string formatada como valor em vez de imprimi-la, use vsprintf().

Exemplo básico

Aqui está o caso mais simples — três placeholders de string preenchidos a partir de um array:

Isso irá exibir:

I like apple, banana, and orange.

Cada %s é substituído, em ordem, pelo próximo elemento de $values.

Especificadores de formato comuns

A string de formato é a mesma usada em toda a família printf. Os especificadores mais úteis são:

Você também pode controlar largura, preenchimento, sinal e precisão entre o % e o especificador:

<?php

// Pad an integer to 5 digits with leading zeros, show the sign, print binary.
vprintf("%05d / %+d / %b\n", [42, 7, 5]);

// Left-align in 10 columns, then right-align in 10 columns.
vprintf("%-10s|%10s|\n", ["left", "right"]);

// Money: two decimal places.
vprintf("Total: \$%01.2f\n", [49.9]);

Saída:

00042 / +7 / 101
left      |     right|
Total: $49.90

Reutilizando um valor com numeração de argumentos

Você pode referenciar um elemento específico do array mais de uma vez com a sintaxe de troca %n$, onde n é a posição baseada em 1:

<?php

vprintf("Hex of %1\$d is %1\$x\n", [255]);

Saída:

Hex of 255 is ff

Aqui %1$d e %1$x leem o primeiro elemento do array (255) e o formatam como decimal e hexadecimal, respectivamente.

Usando o valor de retorno

vprintf() retorna o número de caracteres impressos, o que é útil para registro ou verificações de alinhamento:

<?php

$len = vprintf("Total: \$%01.2f\n", [49.9]);
echo "Printed $len characters.\n";

Saída:

Total: $49.90
Printed 14 characters.

vprintf() vs. funções relacionadas

Regra geral: escolha a versão v quando seus dados estiverem em um array, e a versão s quando quiser a string retornada em vez de exibida.

Erros comuns

• Contagens incompatíveis. Se o array tiver menos elementos do que placeholders, o PHP lança um ArgumentCountError (PHP 8+) ou um aviso em versões mais antigas. Elementos extras do array são simplesmente ignorados.
• Escapar $ em aspas duplas. Um sinal de dólar literal antes de um dígito (como em $5) pode colidir com a interpolação de variáveis do PHP. Use strings de formato com aspas simples ou escape como \$, conforme mostrado acima.
• Esquecer que ele exibe. vprintf() escreve na saída imediatamente — seu valor de retorno é um comprimento, não a string. Use vsprintf() para capturar o resultado.
• Arrays associativos. Apenas os valores são usados, na ordem em que estão armazenados; as chaves são ignoradas. Passe uma lista (array numérico e sequencial) para evitar surpresas.

Prática