Signatur
Beschreibung
mb_strimwidth schneidet einen Multibyte-String ab einer Startposition auf eine maximale Anzahl von Zeichen (Breite) zu. Im Gegensatz zu substr arbeitet die Funktion zeichenorientiert und berücksichtigt dabei korrekt Multibyte-Kodierungen wie UTF-8 oder EUC-JP, sodass keine verstümmelten Zeichen entstehen.
Über den optionalen Parameter $trim_marker kann eine Zeichenfolge angegeben werden, die am Ende des gekürzten Strings angehängt wird (z. B. "..." oder "…"). Die Breite des Markers wird dabei in die Gesamtbreite eingerechnet, sodass der Rückgabewert nie breiter als $width Zeichen ist.
Typische Anwendungsfälle sind die Darstellung von Vorschautexten, Teasern oder Tabelleneinträgen, bei denen ein langer Text auf eine feste Spaltenbreite begrenzt werden muss – insbesondere in Anwendungen mit ostasiatischen Sprachen oder anderen Multibyte-Zeichen.
Die Funktion unterstützt alle Kodierungen, die mb_internal_encoding() kennt. Wird kein $encoding angegeben, wird die aktuell gesetzte interne Kodierung verwendet.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $string Pflicht | string | Der Eingabe-String, der gekürzt werden soll. | |
| $start Pflicht | int | Startposition (in Zeichen) ab der der String ausgewertet wird. Negative Werte werden ab dem Ende des Strings gezählt. | |
| $width Pflicht | int | Maximale Breite des Ergebnisstrings in Zeichen. Negative Werte geben die Anzahl der Zeichen an, die vom Ende des Strings weggelassen werden. | |
| $trim_marker | string | "" | Optionale Zeichenfolge, die ans Ende des gekürzten Strings angehängt wird (z. B. "..."). Ihre Länge wird von $width abgezogen. |
| $encoding | string | mb_internal_encoding() | Die Zeichenkodierung des Strings (z. B. "UTF-8"). Wird kein Wert angegeben, wird die interne Kodierung verwendet. |
Rückgabewert
$width Zeichen gekürzten String zurück, ggf. mit angehängtem $trim_marker. Ist der String kürzer als $width, wird er unverändert zurückgegeben.Beispiele
Einfaches Kürzen eines UTF-8-Strings mit Auslassungszeichen
<?php
mb_internal_encoding('UTF-8');
$text = 'Das ist ein langer Beschreibungstext für ein Produkt.';
$kurz = mb_strimwidth($text, 0, 30, '…');
echo $kurz;
// Ausgabe: Das ist ein langer Beschreib…Kürzen eines Strings mit japanischen Zeichen
<?php
mb_internal_encoding('UTF-8');
$text = 'これは日本語のテキストです。とても長い文章です。';
$kurz = mb_strimwidth($text, 0, 10, '...');
echo $kurz;
// Achtung: Jedes japanische Zeichen zählt als 1 Zeichen
// Ausgabe: これは日本語の...Verwendung mit negativem width-Parameter
<?php
mb_internal_encoding('UTF-8');
$text = 'Abcdefghijklmnopqrstuvwxyz';
// Gibt alles außer den letzten 5 Zeichen aus
$kurz = mb_strimwidth($text, 0, -5);
echo $kurz; // Abcdefghijklmnopqrstu// Wichtig · Fallstricke
Achtung bei ostasiatischen Doppelbyte-Zeichen: In einigen Kodierungen (z. B. EUC-JP) können Zeichen eine Anzeigebreite von 2 haben. mb_strimwidth berücksichtigt in solchen Fällen die Anzeigebreite (Display Width), nicht nur die Anzahl der Codepunkte. Bei reinem UTF-8 und lateinischen Schriften entspricht 1 Zeichen = 1 Breite.
Der $trim_marker muss in der angegebenen Kodierung gültig sein; andernfalls kann es zu unerwartetem Verhalten kommen.
Falls $start und $width zusammen über das Ende des Strings hinausgehen, wird der String einfach bis zum Ende ausgegeben, ohne Fehler.