str_pad()

Purpose

str_pad() lengthens a string until it reaches a target length by adding filler characters. You can add the filler after the text, before it, or split across both sides. Typical uses are zero-padded identifiers, fixed-width text columns, and simple centered labels.

The function never shortens anything. If the string is already long enough, you get it back unchanged.

Signature

Parameters and defaults

• $string: the original text.
• $length: the desired length of the final result. Length is counted in bytes, not visible characters. If it is negative, less than, or equal to the length of the input, no padding takes place.
• $pad_string: the filler. It defaults to a single space. It is repeated as often as needed and cut off if the number of padding characters is not a multiple of its length.
• $pad_type: one of STR_PAD_RIGHT (the default), STR_PAD_LEFT or STR_PAD_BOTH.

Return value and failure cases

The function returns a string. When padding is needed, it is the padded version; otherwise it is the original string. Ordinary length problems do not fail, because a too-small or negative $length simply returns the input.

Invalid configuration is different. In PHP 8, an empty $pad_string or an unsupported $pad_type value is rejected with a ValueError, so check dynamic values before passing them in.

Example 1: the three directions

This example shows the default right padding, left padding with a two-character filler, centered padding, a truncated filler and a no-op.

<?php
$input = "Alien";
echo json_encode([
    str_pad($input, 10),
    str_pad($input, 10, "-=", STR_PAD_LEFT),
    str_pad($input, 10, "_", STR_PAD_BOTH),
    str_pad($input, 6, "___"),
    str_pad($input, 3, "*"),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), PHP_EOL;

["Alien     ","-=-=-Alien","__Alien___","Alien_","Alien"]

The first result contains five trailing spaces. The fourth needs only one extra character, so only the first underscore of the filler is used. The last call asks for a length shorter than the text, so nothing changes.

Example 2: zero-padded codes

Numbers are not strings, so convert them first. This keeps your code explicit and works cleanly with strict typing.

<?php
$orders = [7, 42, 305];
$codes = [];
foreach ($orders as $order) {
    $codes[] = "ORD-" . str_pad((string) $order, 5, "0", STR_PAD_LEFT);
}
echo json_encode($codes), PHP_EOL;

["ORD-00007","ORD-00042","ORD-00305"]

Left padding keeps the digits aligned on the right, which is what you want for identifiers that must sort and compare by fixed width.

Example 3: centering and byte length

<?php
$centered = str_pad("PHP", 8, "*", STR_PAD_BOTH);
$accented = str_pad("é", 4, "*");
echo json_encode([
    $centered,
    $accented,
    strlen($accented),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), PHP_EOL;

["**PHP***","é**",4]

Five padding characters cannot be split evenly around PHP. The left side receives two and the right side receives three. The accented letter occupies two bytes in UTF-8, so only two asterisks are added to reach a length of four bytes.

Edge cases

• Odd padding with STR_PAD_BOTH: the extra character goes on the right.
• Multi-character filler: the filler is repeated and may be cut mid-sequence, so a pattern like -= can end on -.
• Equal length: a $length equal to the current length returns the same text.
• Negative length: this is treated as no padding, not as an error.
• Multibyte text: str_pad() works on bytes. For visible-character alignment with UTF-8, the manual points to mb_str_pad() as the multibyte counterpart.

Common mistakes

1. Expecting truncation. str_pad() does not cut a long string down. Use substr() first if you need a maximum width.
2. Forgetting the direction. The default pads on the right. Numbers usually need STR_PAD_LEFT.
3. Counting characters instead of bytes. Accented letters, emoji and other non-ASCII text can make columns look misaligned.
4. Passing an empty filler. A computed $pad_string that might be empty should be validated first.
5. Ignoring the return value. The function returns a new string and does not modify the variable you passed.
6. Using it for locale-aware number formatting. Padding adds filler only; it does not insert separators or decimals. Use a formatting function for that and pad afterward.

Related functions

• mb_str_pad() pads multibyte strings.
• sprintf() and printf() can also pad with width specifiers.
• str_repeat() builds repeated strings manually.
• strlen() reports byte length.
• substr() shortens a string when you need a hard limit.

Recap

Use str_pad() when a string must reach at least a given byte length. Choose the side with STR_PAD_RIGHT, STR_PAD_LEFT or STR_PAD_BOTH, remember that the filler can be truncated, and expect an unchanged string when the target is not longer than the input. Treat an empty filler or invalid pad type as a programming error, and consider the multibyte alternative for UTF-8 display alignment.