mb_str_pad
Pads a string to a given length in characters, counting multibyte characters as one.
mb_str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT, ?string $encoding = null): string- Added in PHP 8.3.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The input string. |
$length | int | Target length measured in characters (codepoints), not bytes. |
$pad_stringoptional | string= " " | The characters used for padding. May be truncated if it does not divide evenly into the space to fill. |
$pad_typeoptional | int= STR_PAD_RIGHT | STR_PAD_RIGHT, STR_PAD_LEFT or STR_PAD_BOTH. |
$encodingoptional | ?string= null | Character encoding. Null uses the internal encoding. |
Return value
stringThe padded string. If length is less than or equal to the character length of string, the input is returned unchanged.
Errors
Throws a ValueError if pad_string is an empty string or if pad_type is not one of the STR_PAD_* constants; throws a ValueError on an invalid encoding.
mb_str_pad() is the encoding-aware replacement for str_pad(), added in PHP 8.3. The critical difference is the unit: str_pad() counts bytes, so str_pad('café', 10) adds only five spaces because the é costs two bytes. mb_str_pad() counts characters and adds six.
When to reach for it
Use it any time you are building fixed-width text that a human will read and the content may contain accents, umlauts, Cyrillic or emoji: CLI table output, plain-text invoices, fixed-width export files, padded reference numbers. Anywhere you would previously have written str_pad() on user-supplied text, this is the safer call.
What trips people up
Characters are not the same thing as display width. A CJK ideograph or a fullwidth form is one codepoint but occupies two terminal columns, and an emoji built from a ZWJ sequence is several codepoints that render as one glyph. mb_str_pad() will happily pad both to the wrong visual width. If you are aligning columns in a terminal that mixes Latin and CJK text, mb_strimwidth() and its width model are the better tool, or measure with a width-aware helper first.
Padding is skipped entirely when length is already reached — it never truncates.
Example
When to use it
- Align a CLI table of product names that contain accented or non-Latin characters
- Build a fixed-width plain-text export where each field must occupy an exact number of characters
- Left-pad an order reference with zeros when the prefix may contain non-ASCII characters
Frequently asked questions
What is the difference between mb_str_pad and str_pad?
str_pad measures length in bytes while mb_str_pad measures in characters. For ASCII-only input they are identical; for anything with accents or non-Latin script str_pad under-pads because each multibyte character eats several of the byte budget.
What PHP version added mb_str_pad?
PHP 8.3.0. On older versions you have to emulate it, typically with str_pad($s, $len + strlen($s) - mb_strlen($s), $pad, $type).
Does mb_str_pad align CJK or emoji correctly in a terminal?
No. It pads by codepoint count, and fullwidth CJK characters occupy two terminal columns while emoji sequences can be several codepoints in one glyph. Use a display-width-aware approach, such as mb_strimwidth, for terminal column alignment.
More examples
Centring with STR_PAD_BOTH
'Übersicht' is nine characters. Padding to 19 leaves ten dashes split evenly, five each side. Padding to 20 leaves eleven, and the extra one goes on the right — STR_PAD_BOTH always favours the right side when the padding cannot be split evenly.
<?php
mb_internal_encoding('UTF-8');
$title = 'Übersicht';
echo '[', mb_str_pad($title, 19, '-', STR_PAD_BOTH), "]\n";
echo '[', mb_str_pad($title, 20, '-', STR_PAD_BOTH), "]\n";Multi-character pad strings get truncated
Seven characters of padding are needed but the pad string is two characters long, so the last repetition is cut in half. The result is always exactly the requested character length — the var_dump confirms 9 even though the arrows are three bytes each.
<?php
mb_internal_encoding('UTF-8');
echo mb_str_pad('ab', 9, '<>'), "\n";
echo mb_str_pad('ab', 9, '←→'), "\n";
var_dump(mb_strlen(mb_str_pad('ab', 9, '←→')));
Discussion