mb_str_pad — Funktion · PHP-Referenz

Signatur

mb_str_pad(string $input, int $length, string $pad_string = ' ', int $pad_type = STR_PAD_RIGHT, ?string $encoding = null): string

Beschreibung

mb_str_pad() ist das Multibyte-sichere Äquivalent zur klassischen Funktion str_pad(). Während str_pad() die Länge in Bytes misst, arbeitet mb_str_pad() mit der tatsächlichen Anzahl von Zeichen (Codepunkten), sodass Umlaute, Emojis oder CJK-Zeichen korrekt behandelt werden.

Die Funktion eignet sich überall dort, wo Strings auf eine feste Breite gebracht werden müssen – etwa beim Formatieren von Ausgaben in tabellarischer Form, beim Generieren von Rechnungsnummern mit führenden Nullen oder beim Ausrichten von Text in CLIs und Reports, die Nicht-ASCII-Zeichen enthalten.

Der Parameter $pad_type steuert, ob der Füllstring rechts (STR_PAD_RIGHT, Standard), links (STR_PAD_LEFT) oder auf beiden Seiten (STR_PAD_BOTH) angehängt wird. Ist $length kleiner oder gleich der aktuellen Zeichenlänge des Eingabe-Strings, wird der String unverändert zurückgegeben.

Das optionale Argument $encoding erlaubt die explizite Angabe einer Zeichenkodierung (z. B. 'UTF-8'). Wird es weggelassen oder auf null gesetzt, verwendet die Funktion die intern eingestellte Kodierung (mb_internal_encoding()).

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Der zu füllende Eingabe-String.
$length Pflicht	int		Die gewünschte Zeichenlänge des Ergebnis-Strings. Ist dieser Wert kleiner oder gleich der aktuellen Länge von `$input`, wird `$input` unverändert zurückgegeben.
$pad_string	string	' '	Der Füll-String, mit dem aufgefüllt wird. Standardmäßig ein einzelnes Leerzeichen. Der Füll-String wird ggf. wiederholt oder abgeschnitten, um genau die fehlende Breite zu füllen. Ein leerer String führt zu einem `ValueError`.
$pad_type	int	STR_PAD_RIGHT	Gibt an, auf welcher Seite aufgefüllt wird. Gültige Werte: `STR_PAD_RIGHT` (rechts, Standard), `STR_PAD_LEFT` (links), `STR_PAD_BOTH` (beidseitig, bei ungerader Differenz wird rechts ein Zeichen mehr eingefügt).
$encoding	string\|null	null	Die zu verwendende Zeichenkodierung (z. B. `'UTF-8'`). Bei `null` wird die aktuelle interne Kodierung (`mb_internal_encoding()`) verwendet.

Rückgabewert

Typ

string

Beschreibung

Gibt den auf $length Zeichen aufgefüllten String zurück. Ist $input bereits so lang wie oder länger als $length, wird $input unverändert zurückgegeben.

Beispiele

Rechtsbündige Auffüllung mit Leerzeichen (UTF-8-Umlaute)

<?php
$names = ['Anna', 'Ångström', 'Müller', '李明'];
foreach ($names as $name) {
    $padded = mb_str_pad($name, 12, ' ', STR_PAD_RIGHT, 'UTF-8');
    echo '|' . $padded . "|\n";
}

Linksbündige Auffüllung mit führenden Nullen für Rechnungsnummern

<?php
$ids = [1, 42, 999, 12345];
foreach ($ids as $id) {
    echo 'RE-' . mb_str_pad((string)$id, 6, '0', STR_PAD_LEFT) . "\n";
}

RE-000001 RE-000042 RE-000999 RE-012345

Beidseitige Auffüllung mit Emoji als Füllzeichen

<?php
$title = 'Sale';
$padded = mb_str_pad($title, 12, '🎉', STR_PAD_BOTH, 'UTF-8');
echo $padded . "\n";

🎉🎉🎉🎉Sale🎉🎉🎉🎉

// Wichtig · Fallstricke

Unterschied zu str_pad(): str_pad() zählt Bytes, nicht Zeichen. Bei Strings mit Multibyte-Zeichen (Umlaute, CJK, Emojis) liefert str_pad() daher falsche Ergebnisse bezüglich der sichtbaren Zeichenbreite. Seit PHP 8.3 sollte mb_str_pad() bevorzugt werden, sobald Unicode-Zeichen im Spiel sind.

Monospace-Breite vs. Zeichenbreite: Beachte, dass CJK-Zeichen oder bestimmte Emojis im Terminal eine doppelte visuelle Breite einnehmen können (full-width characters). mb_str_pad() zählt Zeichen (Codepunkte), nicht visuelle Spalten. Für eine pixelgenaue visuelle Ausrichtung in Terminals ist ggf. eine separate Behandlung nötig.

ValueError bei leerem Füll-String: Wird $pad_string als leerer String übergeben, wirft die Funktion einen ValueError.

Siehe auch

str_pad mb_strlen mb_substr mb_internal_encoding STR_PAD_RIGHT STR_PAD_LEFT STR_PAD_BOTH