printf()

A função printf() do PHP exibe uma string formatada de acordo com um modelo. Ao contrário de echo, que apenas concatena e imprime os valores como estão, printf() permite controlar exatamente como cada valor é exibido — sua largura, número de casas decimais, preenchimento, sinal e base numérica — inserindo especificadores de formato (marcadores de posição como %s ou %.2f) em uma string de formato. Esta é a ferramenta certa sempre que o layout da saída importa: tabelas alinhadas, valores monetários com duas casas decimais, IDs com zeros à esquerda ou códigos de cores hexadecimais.

Esta página cobre a sintaxe, a anatomia de um especificador de formato, as conversões mais comuns com exemplos executáveis e as funções relacionadas da mesma família.

Sintaxe

printf(string $format, mixed ...$values): int

• $format — uma string de modelo contendo texto literal e um ou mais especificadores de formato.
• $values — os valores substituídos nos especificadores, em ordem.
• Retorna o número de caracteres escritos (o comprimento da saída), não a string em si. printf() imprime diretamente na saída. Se você quiser que a string formatada seja retornada em vez de impressa, use sprintf().

Um exemplo básico

%s é substituído pelo primeiro argumento ($name) formatado como string, e %d pelo segundo ($age) formatado como inteiro com sinal. A saída é:

My name is John Doe and I am 35 years old.

Anatomia de um especificador de formato

Cada especificador começa com % e pode incluir partes opcionais nesta ordem:

%[argnum$][flags][width][.precision]specifier

• flags — ex.: 0 (preencher com zeros), - (alinhar à esquerda), + (sempre mostrar sinal), ' ' (um espaço preenche com aquele caractere).
• width — o número mínimo de caracteres que o campo ocupa.
• .precision — para números de ponto flutuante, o número de dígitos após o ponto decimal; para strings, o comprimento máximo.
• specifier — o tipo de conversão (veja abaixo).

Para exibir um sinal de porcentagem literal, use %%.

Especificadores de conversão comuns

Largura, precisão e preenchimento

É aqui que printf() mostra seu valor. O exemplo abaixo formata um preço com duas casas decimais, preenche um ID com zeros até 5 dígitos e exibe um número como cor hexadecimal:

<?php
$price = 7.5;
$id = 42;
$color = 16711680; // red

printf("Price: $%.2f\n", $price);
printf("Order ID: %05d\n", $id);
printf("Color: #%06X\n", $color);
?>

Saída:

Price: $7.50
Order ID: 00042
Color: #FF0000

%.2f força exatamente duas casas decimais, %05d preenche o inteiro com zeros até uma largura de 5, e %06X produz hexadecimal maiúsculo preenchido com 6 dígitos.

Troca de argumentos

Um especificador pode indicar qual argumento usa com n$, para que você possa reutilizar um valor ou reordenar argumentos sem alterar a lista — útil para strings traduzíveis em que a ordem das palavras varia por idioma:

<?php
printf('%1$s likes %2$s. %2$s likes %1$s too.', 'Ann', 'tea');
?>

Saída:

Ann likes tea. tea likes Ann too.

A família printf

printf() pertence a uma família de funções que compartilham exatamente a mesma sintaxe de formato, mas diferem no que fazem com o resultado:

• sprintf() — retorna a string formatada em vez de imprimi-la. Use quando precisar armazenar ou processar o resultado.
• vprintf() — como printf(), mas recebe os valores como um único array (vprintf($format, $args)), útil quando os argumentos já estão em um array.
• fprintf() — escreve a string formatada em um stream/manipulador de arquivo em vez da saída padrão.

Para formatação de números sensível à localidade (separadores de milhar, moeda), veja number_format().

Quando usar

Use printf() (ou sprintf()) quando o layout da saída importa: colunas alinhadas, valores monetários com casas decimais fixas, identificadores com zeros à esquerda ou geração de strings como cores hexadecimais e URLs. Para saída simples onde a formatação é irrelevante, echo é mais simples e rápido.

Prática