Sobald Ausgaben in einer Konsole, in einem CSV-Export oder auf einem Beleg ordentlich untereinander stehen sollen, braucht es Strings mit einheitlicher Länge. PHP bringt dafür eine Funktion mit, die genau eine Aufgabe erledigt und sie sehr gut erledigt. Dieses Tutorial zeigt Syntax, die drei Pad-Modi und die typischen Praxisfälle vom Zero-Padding bis zur ASCII-Tabelle.
Was macht die Funktion PHP str_pad()?
Wer in PHP Belegnummern mit führenden Nullen darstellt, eine CLI-Tabelle ausrichtet oder einen zentrierten Header in eine Konsole setzen will, greift zu PHP str_pad. Die Funktion füllt einen String auf eine vorgegebene Mindestlänge auf, indem sie ein wiederholtes Pad-Zeichen links, rechts oder beidseitig anhängt. Damit wird sie zum Standard-Werkzeug für alles, was nach festen Spaltenbreiten oder gleichen Zahllängen verlangt.
Bevor Syntax und die drei Pad-Konstanten im Detail folgen, ein Hinweis darauf, warum das Verhalten bei zu langen Strings immer wieder zu Diskussionen führt.
Die Funktion arbeitet im Kern mit drei Konstanten: STR_PAD_LEFT, STR_PAD_RIGHT und STR_PAD_BOTH. Im Default-Fall wird rechts mit Leerzeichen aufgefüllt. Die Reihenfolge der Argumente und das Verhalten bei zu langen Strings sorgen dabei in Code-Reviews regelmäßig für Diskussionen, weil PHP str_pad bei einem längeren Eingabe-String nicht kürzt, sondern unverändert zurückgibt.
Syntax und die vier Parameter
Die Signatur erwartet bis zu vier Argumente: den Eingabestring, die Ziellänge, das Pad-Zeichen und den Pad-Typ. Letzte beide haben sinnvolle Defaults.
<?php
str_pad(
string $string,
int $length,
string $pad_string = ' ',
int $pad_type = STR_PAD_RIGHT
): string
Wichtig zu wissen: Die $length ist die ZIEL-Länge, nicht die Anzahl der hinzugefügten Zeichen. Wer aus '42' eine 8-stellige Belegnummer machen will, ruft PHP str_pad mit $length = 8 auf, nicht mit 6. Der Eingabestring bleibt unverändert, wenn er bereits länger oder gleich lang ist. Wer auf eine exakte Länge bestehen will, kombiniert mit substr() (siehe weiter unten).
Die drei Konstanten STR_PAD_LEFT, RIGHT, BOTH
Die drei Konstanten steuern, wo das Pad-Zeichen eingefügt wird. STR_PAD_RIGHT (Default) hängt rechts an und ist typisch für Spaltenausrichtungen mit linksbündigem Text. STR_PAD_LEFT hängt links an und ist die Wahl für Zero-Padding von Zahlen oder rechtsbündige Spalten. STR_PAD_BOTH verteilt die Pad-Zeichen auf beide Seiten und eignet sich für zentrierte Überschriften.
<?php
echo '|' . str_pad('PHP', 10) . '|' . "\n";
/* |PHP | (rechts gepaddet, default) */
echo '|' . str_pad('PHP', 10, '0', STR_PAD_LEFT) . '|' . "\n";
/* |0000000PHP| (links gepaddet) */
echo '|' . str_pad('PHP', 10, '-', STR_PAD_BOTH) . '|' . "\n";
/* |---PHP----| (beidseitig, mehr rechts) */
Bei STR_PAD_BOTH und ungerader Differenz wandert das zusätzliche Zeichen nach rechts. Aus 'PHP' (3 Zeichen) auf 10 macht PHP str_pad also 3 Striche links und 4 rechts. Wer das umgekehrt haben möchte, pad-pad sich die Strings in zwei Schritten oder berechnet das Padding selbst.
Zero-Padding für Zahlen und Belegnummern
Eines der häufigsten Anwendungsbeispiele ist das Zero-Padding einer fortlaufenden Nummer. Aus 42 wird '00000042', aus 1234 wird '00001234'. Das schafft saubere Sortierungen in Listen und macht Belegnummern auf Berichten optisch einheitlich.
<?php
$beleg = str_pad((string)42, 8, '0', STR_PAD_LEFT);
echo $beleg;
/* 00000042 */
/* Aktenzeichen mit Praefix */
$nr = 42;
$aktenzeichen = 'AZ-' . str_pad((string)$nr, 6, '0', STR_PAD_LEFT);
echo $aktenzeichen;
/* AZ-000042 */
Wichtig ist die explizite Konvertierung mit (string). PHP castet zwar automatisch, doch die explizite Variante macht im Code-Review klar, dass hier ein Integer in einen String umgewandelt wird, bevor PHP str_pad ihn entgegen nimmt. Bei statischen Analysetools wie PHPStan ist das ebenfalls die saubere Lösung.
CLI-Tabellen sauber ausrichten
In Konsolen-Skripten ist PHP str_pad das Mittel der Wahl, um Tabellen mit festen Spaltenbreiten zu erzeugen. Linksbündige Spalten nutzen STR_PAD_RIGHT, rechtsbündige Spalten (typisch für Geldwerte) nutzen STR_PAD_LEFT.
<?php
$kunden = [
['Mueller GmbH', 1234.50],
['Schmidt AG', 89.00],
['Hubel KG', 12345.99],
];
foreach ($kunden as $z) {
$name = str_pad($z[0], 20);
$betrag = str_pad(
number_format($z[1], 2, ',', '.'),
12,
' ',
STR_PAD_LEFT
);
echo $name . $betrag . "\n";
}
/* Mueller GmbH 1.234,50
Schmidt AG 89,00
Hubel KG 12.345,99 */
Die Kombination aus PHP str_pad und number_format() ist das Standard-Werkzeug für Reports in der Konsole, in CSV-Exports oder als Vorbereitung für ein PDF-Layout. Wer einen ASCII-Tabellen-Header braucht, kombiniert das Ganze mit str_repeat('-', $breite) als Trennlinie.
str_pad vs sprintf
Im PHP-Alltag stehen str_pad und sprintf oft nebeneinander. Beide können Zahlen mit führenden Nullen erzeugen, aber sie haben unterschiedliche Stärken. PHP str_pad ist flexibler bei beliebigen Pad-Zeichen (Bindestrich, Stern, Punkt), sprintf ist kompakter, wenn ganze Format-Strings mit mehreren Werten zusammengesetzt werden.
<?php
/* Beide erzeugen denselben Output */
echo str_pad((string)42, 5, '0', STR_PAD_LEFT) . "\n";
/* 00042 */
echo sprintf('%05d', 42) . "\n";
/* 00042 */
/* sprintf mit mehreren Werten */
echo sprintf('Beleg %05d am %s', 42, date('d.m.Y'));
/* Beleg 00042 am 15.05.2026 */
Die Faustregel im Team: sprintf() für Zahlen-Templates und kombinierte Formatierungen, PHP str_pad für Strings mit beliebigen Pad-Zeichen oder für reine Padding-Aufgaben. So bleibt der Code lesbar und keine Funktion wird zwanghaft für Aufgaben gebogen, die der anderen besser liegen.
Multibyte-Falle und mb_str_pad
PHP str_pad arbeitet byte-basiert. Solange ein String nur ASCII enthält, entspricht ein Byte einem Zeichen. Sobald Umlaute oder Emoji ins Spiel kommen, zählen die Mehrbyte-Zeichen mehrfach und das Padding stimmt nicht mehr.
<?php
$titel = 'Müller-Liste';
$pad1 = str_pad($titel, 30);
$pad2 = mb_str_pad($titel, 30);
echo "|$pad1|" . "\n";
echo "|$pad2|" . "\n";
/* str_pad zaehlt Bytes (mehr als 30 in Wirklichkeit)
mb_str_pad zaehlt Zeichen, das Padding wird optisch korrekt */
Seit PHP 8.3 steht mb_str_pad() als Multibyte-Variante zur Verfügung. Sie hat dieselbe Signatur, akzeptiert die gleichen Konstanten und arbeitet zeichenbasiert. Wer PHP 8.2 oder älter im Einsatz hat, kann mit Polyfills oder Wrapper-Funktionen arbeiten, die intern mb_strlen() und str_repeat() kombinieren.
Praxis-Wrapper für fixe Länge
Manchmal reicht das Auffüllen nicht, ein Feld muss exakt N Zeichen lang sein. PHP str_pad alleine garantiert das nicht, weil ein zu langer String unverändert zurückkommt. Ein kleiner Wrapper mit substr() löst das Problem.
<?php
function fixeLaenge(string $wert, int $n): string
{
return substr(str_pad($wert, $n), 0, $n);
}
echo '|' . fixeLaenge('PHP', 10) . '|' . "\n";
/* |PHP | */
echo '|' . fixeLaenge('Sehr langes Feld', 10) . '|' . "\n";
/* |Sehr lange| */
Solche Wrapper sind besonders nützlich beim Erzeugen von Datensätzen mit fixen Spaltenbreiten, etwa für SWIFT-Nachrichten, alte EDI-Formate oder Cobol-Schnittstellen. Wer Multibyte-sicher unterwegs ist, ersetzt substr durch mb_substr und str_pad durch mb_str_pad.
Wie die Funktion intern entscheidet, ob und wo aufgefüllt wird, zeigt das folgende Diagramm im Überblick.
flowchart TD
A[Eingabe-String] --> B{Laenge < Ziel?}
B -->|nein| C[String unveraendert]
B -->|ja| D{Pad-Typ?}
D -->|LEFT| E[Pad-Zeichen links]
D -->|RIGHT| F[Pad-Zeichen rechts]
D -->|BOTH| G[Pad-Zeichen beidseitig]
E --> H[Aufgefuellter String]
F --> H
G --> H
Fazit
Mit PHP str_pad steht ein einfaches und wirkungsvolles Werkzeug für alles bereit, was eine feste Stringlänge braucht. Die drei Konstanten STR_PAD_LEFT, STR_PAD_RIGHT und STR_PAD_BOTH decken Zero-Padding, Spaltenausrichtung und Zentrierung ab. Im Vergleich zu sprintf bleibt PHP str_pad die richtige Wahl, sobald beliebige Pad-Zeichen oder reine Padding-Aufgaben im Vordergrund stehen. Wer mit Umlauten oder Emoji arbeitet, wechselt seit PHP 8.3 auf mb_str_pad() und sichert damit eine optisch korrekte Ausgabe. Damit gehört PHP str_pad zum festen Repertoire jeder Konsolen-Anwendung, jedes Reports und jeder Schnittstelle mit fester Datensatzbreite.
