PHP printf e sprintf

Mostrar 8.5 como 8.50, o número 7 como 007, ou alinhar uma tabela de notas em colunas: com interpolação e concatenação isso dá trabalho. As funções printf e sprintf recebem um modelo com "lacunas formatadas" e preenchem cada lacuna do jeito que você pediu.

A ideia: um carimbo com espaços para preencher

Imagine um carimbo de recibo: "Recebi de        a quantia de R$     ". Cada espaço tem um formato: um é para nome, outro é para valor com centavos. O printf funciona assim: você escreve o modelo uma vez, com marcadores % no lugar das lacunas, e passa os valores na ordem.

O nome vem da linguagem C: print formatted, "imprimir formatado". O s de sprintf é de string: "formatar e devolver como texto".

printf e sprintf

<?php
$nome = "Ana";
$idade = 29;
printf("%s tem %d anos.\n", $nome, $idade);
$frase = sprintf("%s tem %d anos.", $nome, $idade);
echo $frase, "\n";

printf(…)

Monta o texto e mostra na tela, como um echo.

"%s tem %d anos.\n"

O modelo (em inglês, format string). Cada % seguido de uma letra é uma lacuna.

%s

Lacuna para um texto (string). Recebe o 1º valor, $nome.

%d

Lacuna para um número inteiro (decimal, "na base 10"). Recebe o 2º valor, $idade.

$nome, $idade

Os valores, na ordem das lacunas.

sprintf(…)

Faz o mesmo, mas não mostra: devolve o texto pronto, para você guardar numa variável, juntar com outro texto ou passar para outra função.

$ php primeiro.php
Ana tem 29 anos.
Ana tem 29 anos.

Na prática, sprintf é o mais útil dos dois: você formata o valor e depois o usa onde quiser (num heredoc, num HTML, num arquivo). printf é um atalho para echo sprintf(…).

Os marcadores principais

%s, %d e %f

<?php
printf("[%s]\n", 3.14159);
printf("[%d]\n", 3.99);
printf("[%d]\n", "42 laranjas");
printf("[%f]\n", 3.14159);
printf("[%.2f]\n", 3.14159);
printf("[%.1f]\n", 8.75);

$ php marcadores.php
[3.14159]        « %s: o valor como texto, do jeito que está
[3]              « %d: só a parte inteira (corta, não arredonda!)
[42]             « %d: pegou o número do começo do texto
[3.141590]       « %f: sempre 6 casas decimais
[3.14]           « %.2f: 2 casas decimais, arredondando
[8.8]            « %.1f: 1 casa

Os colchetes [ ] estão no modelo só para você ver onde o valor começa e termina. O mais usado de todos é o %.2f: "número com 2 casas decimais", perfeito para dinheiro e notas.

%

Começa uma lacuna.

.2

A precisão: quantas casas depois do ponto.

f

O tipo: número com casas decimais (float).

O %f não usa vírgula

O laboratório da Ana está em português do Brasil (LANG=pt_BR.UTF-8), e mesmo assim:

$ echo $LANG
pt_BR.UTF-8
$ php -r 'printf("%.2f\n", 1234.5);'
1234.50

Ponto decimal e nenhum separador de milhar. O PHP não usa o idioma do sistema para formatar números: o printf sempre sai no formato americano. (Quem vem do Java estranha: lá o printf em pt_BR dá 1234,50.)

Para o formato brasileiro 1.234,50, a ferramenta certa é o number_format, assunto da próxima aula. Existe uma função setlocale que, em algumas instalações, faz o %f minúsculo usar vírgula; mas ela depende de o idioma estar instalado no servidor (no laboratório da Ana, não fez diferença) e muda o comportamento do programa inteiro. Se quiser garantir o ponto em qualquer situação (num arquivo CSV ou JSON, por exemplo), use %F maiúsculo, que nunca olha o idioma.

<?php
$preco = 4.5;
$quilos = 3;
$total = $preco * $quilos;
echo "Total: R$ $total";

<?php
$preco = 4.5;
$quilos = 3;
$total = $preco * $quilos;
printf("Total: R$ %.2f", $total);

Largura, alinhamento e zeros

Entre o % e a letra, você pode dizer a largura mínima do campo. O valor é completado com espaços até essa largura: à esquerda (alinhado à direita) por padrão, ou à direita com um - (alinhado à esquerda).

<?php
printf("[%5d]\n", 42);
printf("[%-5d]\n", 42);
printf("[%05d]\n", 42);
printf("[%10s]\n", "Ana");
printf("[%-10s]\n", "Ana");
printf("[%'.10s]\n", "Ana");
printf("[%8.2f]\n", 3.14159);
printf("[%08.2f]\n", 3.14159);
printf("[%+d] [%+d]\n", 5, -5);
printf("[%.3s]\n", "Conceição");

$ php largura.php
[   42]          « largura 5, alinhado à direita
[42   ]          « o - alinha à esquerda
[00042]          « o 0 completa com zeros
[       Ana]
[Ana       ]
[.......Ana]     « '. (aspa simples + caractere) escolhe o caractere de preenchimento
[    3.14]       « largura 8 no total (contando o ponto), 2 casas
[00003.14]
[+5] [-5]        « o + mostra o sinal sempre
[Con]            « em %s, o .3 corta o texto em 3 caracteres

A ordem das partes é sempre: % → opções (-, 0, +, 'x) → largura → .precisão → tipo. Se o valor for maior que a largura, nada é cortado: a largura é só um mínimo.

A tabela de notas da Ana

Juntando largura e precisão, a Ana monta o boletim da turma com as colunas alinhadas:

<?php
printf("%-10s %6s\n", "Aluno", "Nota");
printf("%-10s %6.2f\n", "Bruno", 8.5);
printf("%-10s %6.2f\n", "Carla", 10);
printf("%-10s %6.2f\n", "Davi", 6.75);
printf("%-10s %6.2f\n", "Eduarda", 9.333);

%-10s

O nome, alinhado à esquerda, ocupando 10 posições.

(espaço)

Um espaço fixo entre as colunas.

%6.2f

A nota, alinhada à direita em 6 posições, com 2 casas. Assim os pontos decimais ficam um embaixo do outro.

%6s

No cabeçalho, o título "Nota" também ocupa 6 posições, alinhado à direita, para ficar em cima dos números.

$ php boletim.php
Aluno        Nota
Bruno        8.50
Carla       10.00
Davi         6.75
Eduarda      9.33

Quando você aprender o foreach, vai fazer o mesmo com uma lista de alunos de qualquer tamanho, escrevendo o printf uma vez só.

$ php -r 'printf("%-10s %6.2f\n", "Conceição", 7);'
Conceição   7.00

<?php
printf("%s %s\n", "Maçã", 4.5);
printf("%s %s\n", "Uva", 7.9);
printf("%s %s\n", "Banana", 3.25);

<?php
printf("%s %5.2f\n", mb_str_pad("Maçã", 10), 4.5);
printf("%-10s %5.2f\n", "Uva", 7.9);
printf("%-10s %5.2f\n", "Banana", 3.25);

Outros marcadores: %x, %b, %e, %%

<?php
printf("[%x] [%X] [%o] [%b]\n", 255, 255, 8, 5);
printf("[%08b]\n", 5);
printf("[%e]\n", 1234.5678);
printf("[%.2e]\n", 0.000123);
printf("[%c]\n", 65);
printf("Aprovação: %d%%\n", 87);

$ php outros.php
[ff] [FF] [10] [101]   « hexadecimal, hexadecimal maiúsculo, octal, binário
[00000101]             « binário com 8 dígitos
[1.234568e+3]          « notação científica: 1,234568 × 10³
[1.23e-4]              « 1,23 × 10⁻⁴
[A]                    « o caractere de código 65
Aprovação: 87%         « %% = um sinal de porcentagem

O %% é importante: como o % começa uma lacuna, para escrever o símbolo você precisa de dois. Um exemplo com cor: sprintf("#%02x%02x%02x", 255, 136, 0) dá #ff8800.

Argumentos numerados: %1$s

Normalmente, as lacunas pegam os valores na ordem. Com %N$, você escolhe qual valor vai em cada lacuna: %1$s é "o 1º valor, como texto", %2$s é "o 2º". Assim dá para trocar a ordem ou repetir um valor.

<?php
printf('%2$s, %1$s' . "\n", "Ana", "Souza");
printf('%1$s! %1$s! %1$s!' . "\n", "Bis");
printf('%2$s tirou %1$.1f' . "\n", 9.5, "Ana");

$ php numerados.php
Souza, Ana             « o 2º antes do 1º
Bis! Bis! Bis!         « o mesmo valor três vezes
Ana tirou 9.5          « %1$.1f: o 1º valor, com 1 casa

Esse recurso é muito usado em sites traduzidos: em português é "Souza, Ana", em outro idioma pode ser "Ana Souza", e só o modelo muda.

Formas diferentes e qual usar

Quando dá errado

<?php
printf("%s tem %d anos\n", "Ana");

$ php faltou.php

Fatal error: Uncaught ArgumentCountError: 3 arguments are required, 2 given in /home/ana/php/faltou.php:2
Stack trace:
#0 /home/ana/php/faltou.php(2): printf('%s tem %d anos\n', 'Ana')
#1 {main}
  thrown in /home/ana/php/faltou.php on line 2

<?php
printf("Desconto de 10% para Ana\n");

$ php porcento.php

Fatal error: Uncaught ArgumentCountError: 2 arguments are required, 1 given in /home/ana/php/porcento.php:2
Stack trace:
#0 /home/ana/php/porcento.php(2): printf('Desconto de 10%...')
#1 {main}
  thrown in /home/ana/php/porcento.php on line 2

<?php
printf("Idade: %i anos\n", 29);

$ php tipo.php

Fatal error: Uncaught ValueError: Unknown format specifier "i" in /home/ana/php/tipo.php:2
Stack trace:
#0 /home/ana/php/tipo.php(2): printf('Idade: %i anos\n', 29)
#1 {main}
  thrown in /home/ana/php/tipo.php on line 2

<?php
$nota = "8,5";
printf("Nota: %.2f\n", $nota);

$ php virgula.php
Nota: 8.00

<?php
$notas = [8.5, 9];
printf("Notas: %s\n", $notas);

$ php lista.php

Warning: Array to string conversion in /home/ana/php/lista.php on line 3
Notas: Array

Referência

Exercícios

<?php
printf("%-10s %6s\n", "Aluno", "Nota");
printf("%s %s\n", "Carla", 10);
printf("%s %s\n", "Davi", 6.75);

<?php
printf("%-10s %6s\n", "Aluno", "Nota");
printf("%-10s %6.2f\n", "Carla", 10);
printf("%-10s %6.2f\n", "Davi", 6.75);

Resumo

• printf mostra; sprintf devolve o texto. Os dois recebem um modelo com lacunas % e os valores na ordem.
• %s texto, %d inteiro (corta), %f decimal, %.2f duas casas (arredonda), %% o símbolo de porcentagem.
• Largura: %5d (à direita), %-10s (à esquerda), %05d (zeros). A largura conta bytes: acentos desalinham.
• %1$s escolhe qual argumento usar; escreva o modelo com aspas simples.
• O %f sai com ponto, mesmo com o sistema em português. Para 1.234,50, use number_format.
• Faltou valor para uma lacuna? ArgumentCountError. Um % solto? Unknown format specifier.