str_pad()

Функция PHP str_pad() дополняет строку другой строкой до заданной длины. Она незаменима, когда вывод должен иметь фиксированную ширину: дополнение чисел нулями (007), выравнивание колонок в отчёте, формирование записей фиксированной ширины для устаревших систем или центрирование метки внутри баннера.

На этой странице рассматриваются синтаксис, каждый режим дополнения, правила, которые часто вводят в заблуждение, и практические примеры для запуска.

Синтаксис

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

Параметры

Функция возвращает дополненную строку. Она никогда не усекает — только удлиняет строку или возвращает её как есть.

Базовый пример: дополнение числа нулями

Распространённое применение — принудительное задание числу фиксированной ширины путём дополнения ведущими нулями.

"Hello" состоит из 5 символов, а мы запросили длину 10, поэтому str_pad() добавляет 5 символов "0" слева:

00000Hello

Три режима дополнения

Четвёртый аргумент определяет, с какой стороны добавляется дополнение.

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

Вывод:

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

При использовании STR_PAD_BOTH дополнение делится между двумя сторонами. Когда количество символов дополнения нечётное, лишний символ добавляется справа:

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

Практический пример: выравнивание отчёта

Поскольку str_pad() создаёт столбцы фиксированной ширины, она удобна для таблиц в виде обычного текста. Дополняйте метки справа, а числа — слева:

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

Вывод:

Apples        3
Bread        12
Milk          1

Особенности и примечания

• Строка никогда не сокращается. Если $length меньше входной строки, str_pad() возвращает входную строку без изменений. Используйте substr(), если также нужно ограничить длину.
• Многосимвольные строки дополнения могут «перехлестнуть» — но str_pad() обрезает их. Дополнение "x" до длины 6 строкой "ab" даст "xababa": строка дополнения повторяется и обрезается точно до целевой длины.
• Функция считает байты, а не символы. При работе с многобайтовым (UTF-8) текстом акцентированный или не-латинский символ может занимать несколько байт, поэтому видимая ширина может отличаться от $length. Встроенной функции mb_str_pad() не было до PHP 8.3.
• Для чисел с ведущими нулями sprintf() с форматом вроде %05d зачастую нагляднее, чем str_pad().

Связанные функции

• str_repeat() — повторить строку заданное количество раз.
• sprintf() — форматировать строки с указанием ширины и точности.
• number_format() — форматировать числа с разделителями тысяч и десятичных знаков.
• strlen() — получить длину, относительно которой работает str_pad().
• trim() — обратная идея: удалить окружающие символы.

Практика