vsprintf()

Introdução

A função vsprintf() no PHP formata uma string usando um array de argumentos e retorna o resultado em vez de imprimi-lo. Pense nela como a versão baseada em array de sprintf(): a string de formato e os marcadores funcionam de forma idêntica, mas os valores vêm de um array em vez de uma lista de parâmetros separados.

O "v" no nome significa vetor (array). Esta é a função ideal quando seus valores já estão em um array — por exemplo, uma linha de banco de dados, uma linha CSV analisada ou o resultado de explode() — e você não quer espalhá-los em argumentos individuais.

Este capítulo abrange a sintaxe, os especificadores de formato mais comuns, casos reais de formatação (preenchimento, números, reordenação de argumentos) e como vsprintf() difere da família relacionada printf/sprintf.

Sintaxe

vsprintf(string $format, array $values): string

O valor de retorno é a string completamente formatada. Ao contrário de vprintf(), nada é enviado para a saída — você decide o que fazer com o valor retornado.

Nota: A partir do PHP 8.0, passar poucos valores para os marcadores lança um ValueError. Em versões anteriores, isso gerava um aviso e retornava false.

Primeiro exemplo

Saída:

I like apple, banana, and orange.

Cada marcador %s é substituído, da esquerda para a direita, pelo próximo elemento de $values. A string finalizada é retornada e armazenada em $result — ela só é impressa porque chamamos echo explicitamente.

Especificadores de formato comuns

A letra após % controla como o valor correspondente é renderizado:

Os especificadores também podem carregar flags, uma largura e uma precisão entre o % e a letra (por exemplo %05d ou %.2f), que é onde vsprintf() se torna genuinamente poderoso.

Preenchimento e formatação de números

<?php

// %05d  → pad the integer with zeros to a width of 5
// %01.2f → at least 1 digit, exactly 2 decimal places
// %-10s → left-align the string in a 10-char field
$row = [42, 42.5, 'left'];
echo vsprintf("ID:%05d  Price:\$%01.2f  Name:[%-10s]", $row);

Saída:

ID:00042  Price:$42.50  Name:[left      ]

Este é o motivo típico para escolher vsprintf(): você tem um registro (aqui um array $row) e um modelo fixo, e deseja uma saída alinhada, com preenchimento de zeros e estilo monetário, sem concatenar strings manualmente.

Reutilizando argumentos com marcadores posicionais

Um marcador na forma %n$ refere-se ao n-ésimo elemento do array (baseado em 1), então você pode usar o mesmo valor mais de uma vez ou alterar sua ordem independentemente do array:

<?php

$values = ['Sam', 30];
echo vsprintf('%1$s is %2$d years old. Hi %1$s!', $values);

Saída:

Sam is 30 years old. Hi Sam!

Aqui %1$s é usado duas vezes, embora 'Sam' apareça apenas uma vez no array.

vsprintf() vs. o restante da família

Estas quatro funções compartilham exatamente as mesmas regras de string de formato; elas diferem apenas na forma como os argumentos são passados e o que fazem com o resultado:

A regra geral é: use a variante v* quando seus dados já estão em um array, e use as variantes sprintf/vsprintf (sem o print interno) quando quiser a string de volta em vez de saída imediata.

Armadilhas comuns

• Poucos valores lançam um erro. Se o array tiver menos elementos do que o formato tem marcadores, o PHP 8+ lança um ValueError. Certifique-se de que o comprimento do array corresponde ao número de especificadores (não posicionais).
• Valores extras são ignorados. Mais elementos do que marcadores é permitido — o excesso é descartado silenciosamente.
• Chaves são ignoradas para marcadores sequenciais. vsprintf() consome o array por posição, não por chave, portanto um array associativo é lido na ordem de inserção.
• Escape de sinais de porcentagem literais como %%, caso contrário o PHP tentará ler o caractere seguinte como um especificador.

Funções relacionadas

• sprintf() — mesma formatação com argumentos separados.
• vprintf() — como vsprintf(), mas imprime o resultado diretamente.
• printf() — imprime uma string formatada a partir de argumentos separados.
• number_format() — formata números com agrupamento de milhares.

Prática