str_pad()

The PHP str_pad() function pads a string with another string until it reaches a given length. You reach for it whenever output needs a fixed width: zero-padding numbers (007), aligning columns in a report, building fixed-width records for legacy systems, or centering a label inside a banner.

This page covers the syntax, each padding mode, the rules that trip people up, and practical examples you can run.

Syntax

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

Parameters

The function returns the padded string. It never truncates — it only ever makes a string longer or returns it as-is.

Basic example: zero-padding a number

A common use is forcing a number to a fixed width by padding it with leading zeros.

"Hello" is 5 characters long and we asked for a length of 10, so str_pad() adds 5 "0" characters on the left:

00000Hello

The three padding modes

The fourth argument controls which side receives the padding.

<?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---
?>

Output:

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

With STR_PAD_BOTH, padding is split between the two sides. When the number of pad characters is odd, the extra one goes on the right:

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

Practical example: aligning a report

Because str_pad() produces fixed-width columns, it is handy for plain-text tables. Pad labels to the right and numbers to the left:

<?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";
}
?>

Output:

Apples        3
Bread        12
Milk          1

Gotchas and notes

• It never shrinks a string. If $length is shorter than the input, str_pad() returns the input unchanged. Use substr() if you also need to cap the length.
• Multi-character pad strings can overshoot — but str_pad() clips them. Padding "x" to length 6 with "ab" yields "xababa": the pad string repeats and is cut off exactly at the target length.
• It counts bytes, not characters. With multibyte (UTF-8) text, an accented or non-Latin character may be several bytes, so the visible width can differ from $length. There is no built-in mb_str_pad() before PHP 8.3.
• For zero-padded numbers, sprintf() with a format like %05d is often clearer than str_pad().

Related functions

• str_repeat() — repeat a string a fixed number of times.
• sprintf() — format strings with width and precision specifiers.
• number_format() — format numbers with grouped thousands and decimals.
• strlen() — get the length str_pad() measures against.
• trim() — the inverse idea: remove surrounding characters.

Practice