Como adicionar zeros à esquerda a um número em PHP: 4 maneiras funcionais

Zeros à esquerda em PHP: por que é importante e como não errar

Imagine a situação: você está escrevendo uma loja online e precisa exibir o número do pedido. O cliente vê "Pedido nº 42" e ao lado "Pedido nº 7". Parece desleixado, certo? Dá logo vontade de fazer "Pedido nº 00042" e "Pedido nº 00007". Ou você trabalha com datas: o mês de janeiro deve ser 01, e não apenas 1. É aí que entram os zeros à esquerda em PHP.

A pergunta "Formatting a number with leading zeros in PHP" é uma das mais populares no Stack Overflow. Milhares de desenvolvedores procuram a resposta de como transformar o número 5 em 005 ou 42 em 0042. Parece um detalhe, mas sem a abordagem correta, você pode ter bugs, especialmente ao trabalhar com bancos de dados ou APIs.

Neste artigo, mostrarei 4 maneiras funcionais de adicionar zeros à esquerda a um número em PHP. Você aprenderá a diferença entre sprintf e str_pad, quando usar printf e por que o bom e velho substr também pode ajudar. Vamos lá!

Método 1: sprintf — o rei da formatação

A função sprintf é, provavelmente, a maneira mais elegante de resolver o problema. Ela veio para o PHP da linguagem C e sabe formatar strings de acordo com um padrão. Para zeros à esquerda, usa-se o especificador %0Nd, onde N é o comprimento total do número incluindo os zeros.

Exemplo básico

<?php\n$number = 7;\n$formatted = sprintf("%05d", $number);\necho $formatted; // Exibe: 00007\n?>\n

Vamos analisar o padrão "%05d":

\n
• % — início do especificador
\n
• 0 — preencher com zeros, não com espaços
\n
• 5 — comprimento total da string (5 caracteres)
\n
• d — número inteiro (decimal)
\n

Trabalhando com números negativos

Observe: se o número for negativo, os zeros à esquerda aparecerão após o sinal de menos:

<?php\n$number = -42;\necho sprintf("%05d", $number); // Exibe: -0042\n?>\n

Comprimento dinâmico

Se o comprimento necessário não for conhecido antecipadamente, você pode usar * no padrão:

<?php\n$number = 123;\n$length = 8;\necho sprintf("%0{$length}d", $number); // Exibe: 00000123\n// Ou usando *\necho sprintf("%0*d", $length, $number); // Exibe: 00000123\n?>\n

Vantagens: flexibilidade, legibilidade, suporte a diferentes tipos de dados.
\nDesvantagens: é preciso lembrar a sintaxe dos especificadores.

Método 2: str_pad — simplicidade e clareza

A função str_pad trabalha no nível de strings. Você pega o número, converte para string e "preenche" com zeros à esquerda até o comprimento desejado. É intuitivo até para iniciantes.

Sintaxe

<?php\n$number = 7;\n$formatted = str_pad($number, 5, "0", STR_PAD_LEFT);\necho $formatted; // Exibe: 00007\n?>\n

Parâmetros:

\n
• $number — string de entrada (o número é convertido automaticamente)
\n
• 5 — comprimento desejado do resultado
\n
• "0" — caractere para preenchimento
\n
• STR_PAD_LEFT — preencher à esquerda (existem também STR_PAD_RIGHT e STR_PAD_BOTH)
\n

Detalhe importante: se o número for mais longo

Se o número original já for maior que o comprimento especificado, str_pad simplesmente o retorna como está:

<?php\necho str_pad(123456, 3, "0", STR_PAD_LEFT); // Exibe: 123456 (não corta!)\n?>\n

Comparação com sprintf

<?php\n$number = 42;\necho sprintf("%05d", $number);   // 00042\necho str_pad($number, 5, "0", STR_PAD_LEFT); // 00042\n// O resultado é o mesmo, mas o código é lido de forma diferente\n?>\n

Vantagens: sintaxe óbvia, não precisa memorizar especificadores.
\nDesvantagens: funciona apenas com strings, não tem embutido