mb_strwidth — Funktion · PHP-Referenz

Signatur

mb_strwidth(string $string, ?string $encoding = null): int

Beschreibung

mb_strwidth() berechnet die Anzeigebreite eines Strings in Terminalbreiten (Spalten), nicht die Anzahl der Bytes oder Zeichen. Dies ist besonders relevant für ostasiatische Schriften (Chinesisch, Japanisch, Koreanisch – CJK), deren Zeichen in Monospace-Fonts typischerweise doppelt so breit sind wie lateinische Zeichen.

Die Funktion unterscheidet zwischen folgenden Zeichenklassen: Nullbreite (z. B. Steuerzeichen, 0 Spalten), Halbbreite (normale ASCII- und lateinische Zeichen, 1 Spalte) und Vollbreite (CJK-Ideogramme, Fullwidth-Formen, 2 Spalten). Diese Unterscheidung entspricht dem Unicode-Standard für Anzeigebreiten.

Typische Anwendungsfälle sind die korrekte Ausrichtung von Tabellen oder Menüs in CLI-Anwendungen, das Abschneiden von Text auf eine maximale Anzeigebreite (in Kombination mit mb_strimwidth()) sowie die Formatierung von gemischtem Text (Lateinisch + CJK) in fixer Spaltenbreite.

Ohne Angabe des Parameters $encoding wird die intern gesetzte Standardkodierung (via mb_internal_encoding()) verwendet. Für den täglichen Einsatz mit UTF-8 ist die explizite Angabe von 'UTF-8' empfehlenswert.

Parameter

Name	Typ	Default	Beschreibung
$string Pflicht	string		Der zu messende Eingabe-String, dessen Anzeigebreite in Spalten berechnet werden soll.
$encoding	?string	null	Die Zeichenkodierung des Strings, z. B. `'UTF-8'` oder `'EUC-JP'`. Wird `null` übergeben oder der Parameter weggelassen, gilt die interne Kodierung gemäß `mb_internal_encoding()`.

Rückgabewert

Typ

int

Beschreibung

Die Anzeigebreite des Strings in Spalten als nicht-negative Ganzzahl. Vollbreit-Zeichen tragen 2, Halbbreit-Zeichen 1 und Nullbreite-Zeichen 0 zur Summe bei.

Beispiele

Vergleich lateinischer und CJK-Zeichen

<?php
// Rein lateinischer String: jedes Zeichen = 1 Spalte
$latin = 'Hello';
echo mb_strwidth($latin, 'UTF-8'); // 5
echo PHP_EOL;

// CJK-Zeichen: jedes Zeichen = 2 Spalten
$cjk = '日本語';
echo mb_strwidth($cjk, 'UTF-8'); // 6
echo PHP_EOL;

// Gemischter String
$mixed = 'Hi日本';
echo mb_strwidth($mixed, 'UTF-8'); // 2 + 4 = 6

5 6 6

Tabellenzeilen gleichmäßig ausrichten (CLI)

<?php
function pad_to_width(string $text, int $targetWidth, string $enc = 'UTF-8'): string {
    $currentWidth = mb_strwidth($text, $enc);
    $padding = max(0, $targetWidth - $currentWidth);
    return $text . str_repeat(' ', $padding);
}

$rows = [
    ['Name',   'Breite'],
    ['Alice',  'eng'],
    ['日本太郎', 'CJK'],
    ['Ján',    'diakr.'],
];

foreach ($rows as [$name, $label]) {
    echo '| ' . pad_to_width($name, 12) . '| ' . $label . PHP_EOL;
}

// Wichtig · Fallstricke

Steuerzeichen und Nullbreite: Bestimmte Unicode-Zeichen wie Zero-Width Joiner (U+200D) oder Combining-Zeichen werden als Nullbreite (0 Spalten) gezählt, sind aber im String vorhanden – dies kann bei ungenauen Längenmessungen zu Verwirrung führen.

Emoji: Viele Emoji-Zeichen gelten als Vollbreite (2 Spalten), jedoch verhält sich die Berechnung je nach PHP-Version und zugrunde liegender Unicode-Datenbank unterschiedlich. Für verlässliche Emoji-Breitenmessung sollte der Unicode-Standard der verwendeten PHP-Version geprüft werden.

Zusammenspiel mit mb_strimwidth(): Zum Abschneiden eines Strings auf eine bestimmte Anzeigebreite ist mb_strimwidth() die passende Ergänzung zu mb_strwidth().

Siehe auch

mb_strimwidth mb_strlen mb_internal_encoding mb_substr