str_pad()

A função PHP str_pad() preenche uma string com outra string até que ela atinja um comprimento determinado. Você a utiliza sempre que a saída precisa ter largura fixa: preenchimento de números com zeros (007), alinhamento de colunas em um relatório, construção de registros de largura fixa para sistemas legados ou centralização de um rótulo dentro de um banner.

Esta página aborda a sintaxe, cada modo de preenchimento, as regras que costumam confundir e exemplos práticos que você pode executar.

Sintaxe

str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT): string

Parâmetros

A função retorna a string preenchida. Ela nunca trunca — apenas torna a string mais longa ou a retorna como está.

Exemplo básico: preenchimento de número com zeros

Um uso comum é forçar um número a ter largura fixa preenchendo-o com zeros à esquerda.

"Hello" tem 5 caracteres e solicitamos um comprimento de 10, então str_pad() adiciona 5 caracteres "0" à esquerda:

00000Hello

Os três modos de preenchimento

O quarto argumento controla qual lado recebe o preenchimento.

<?php
echo str_pad("Hi", 8, "-", STR_PAD_RIGHT), "\n"; // Hi------
echo str_pad("Hi", 8, "-", STR_PAD_LEFT),  "\n"; // ------Hi
echo str_pad("Hi", 8, "-", STR_PAD_BOTH),  "\n"; // ---Hi---
?>

Saída:

Hi------
------Hi
---Hi---

Com STR_PAD_BOTH, o preenchimento é dividido entre os dois lados. Quando o número de caracteres de preenchimento é ímpar, o extra vai para a direita:

<?php
echo str_pad("Hi", 7, "-", STR_PAD_BOTH), "\n"; // --Hi---
?>

Exemplo prático: alinhamento de relatório

Como str_pad() produz colunas de largura fixa, é útil para tabelas em texto simples. Preencha rótulos à direita e números à esquerda:

<?php
$items = ["Apples" => 3, "Bread" => 12, "Milk" => 1];

foreach ($items as $name => $qty) {
    echo str_pad($name, 10) . str_pad($qty, 5, " ", STR_PAD_LEFT) . "\n";
}
?>

Saída:

Apples        3
Bread        12
Milk          1

Armadilhas e observações

• Ela nunca reduz uma string. Se $length for menor que a entrada, str_pad() retorna a entrada sem alterações. Use substr() se também precisar limitar o comprimento.
• Strings de preenchimento com múltiplos caracteres podem ultrapassar — mas str_pad() as corta. Preencher "x" até o comprimento 6 com "ab" resulta em "xababa": a string de preenchimento se repete e é cortada exatamente no comprimento alvo.
• Ela conta bytes, não caracteres. Com texto multibyte (UTF-8), um caractere acentuado ou não latino pode ter vários bytes, então a largura visível pode diferir de $length. Não existe mb_str_pad() nativo antes do PHP 8.3.
• Para números com preenchimento de zeros, sprintf() com um formato como %05d costuma ser mais claro do que str_pad().

Funções relacionadas

• str_repeat() — repete uma string um número fixo de vezes.
• sprintf() — formata strings com especificadores de largura e precisão.
• number_format() — formata números com agrupamento de milhares e casas decimais.
• strlen() — obtém o comprimento que str_pad() usa como referência.
• trim() — a ideia inversa: remove caracteres ao redor.

Prática