wordwrap()

Einführung

Die Funktion wordwrap() in PHP bricht einen String auf mehrere Zeilen um, sodass keine Zeile eine bestimmte Breite überschreitet. Sie durchläuft den String und fügt einen Zeilenumbruch an der letzten Leeerstelle vor dem Erreichen des Limits ein, damit Wörter intakt bleiben. Dies ist nützlich für die Formatierung von Nur-Text-Ausgaben — E-Mails, Protokolldateien, Konsolennachrichten oder überall dort, wo eine feste Spaltenbreite benötigt wird und kein CSS für den Zeilenumbruch zur Verfügung steht.

Syntax

wordwrap(string $string, int $width = 75, string $break = "\n", bool $cut_long_words = false): string

Die Funktion gibt einen neuen String zurück — sie verändert den Original-String nicht. Zu beachten ist, dass wordwrap() an Leerzeichen umbricht, nicht an allgemeinen Wortgrenzen; eine lange Folge von Nicht-Leerzeichen wird nur dann getrennt, wenn $cut_long_words auf true gesetzt ist.

Einfaches Beispiel

Einen Satz bei 20 Zeichen umbrechen:

Ausgabe:

This is a long piece
of text that needs
to be wrapped.

Keine Zeile überschreitet 20 Zeichen. Jeder Umbruch ersetzt das Leerzeichen an der letzten Wortgrenze, die innerhalb des Limits passt, sodass Wörter nie getrennt werden.

Umbrechen für HTML mit einem benutzerdefinierten Umbruchzeichen

Das Argument $break kann ein beliebiger String sein, nicht nur ein Zeilenumbruch. Um Text in HTML umzubrechen, wird ein <br />-Tag verwendet (kombiniert mit \n, damit der Quellcode lesbar bleibt):

<?php

$text = "The quick brown fox jumped over the lazy dog.";
echo wordwrap($text, 15, "<br />\n");

Ausgabe:

The quick brown<br />
fox jumped over<br />
the lazy dog.

Wenn das Ziel lediglich ist, vorhandene Zeilenumbrüche in <br>-Tags umzuwandeln, empfiehlt sich stattdessen nl2br() — wordwrap() dient zum Erstellen der Zeilenumbrüche, nl2br() zum Konvertieren vorhandener.

Lange Wörter trennen

Standardmäßig bleibt ein Wort, das länger als $width ist, vollständig und überläuft die Zeile. Durch Übergabe von true als viertes Argument wird die Funktion gezwungen, innerhalb langer Wörter zu trennen:

<?php

$word = "Supercalifragilisticexpialidocious";

echo "Default (no cut):\n";
echo wordwrap($word, 10, "\n"), "\n\n";

echo "With cut:\n";
echo wordwrap($word, 10, "\n", true);

Ausgabe:

Default (no cut):
Supercalifragilisticexpialidocious

With cut:
Supercalif
ragilistic
expialidoc
ious

Die Trennoption sollte für Inhalte verwendet werden, die eine harte Spaltenbreite einhalten müssen — beispielsweise Ausgaben im Terminal mit fester Breite oder URLs, die sonst den Rand überschreiten würden.

Häufige Fallstricke

• Vorhandene Zeilenumbrüche werden nicht normalisiert. wordwrap() zählt Zeichen zwischen Umbruchpunkten; Text, der bereits eigene Zeilenumbrüche enthält, wird nicht neu umgebrochen. Falls nötig, sollte die Eingabe vorher bereinigt werden.
• Die Breite wird in Bytes, nicht in Zeichen gemessen. Wie die meisten klassischen String-Funktionen von PHP arbeitet wordwrap() byte-basiert. Multibyte-Zeichen (UTF-8) können daher falsch gezählt und bei aktiviertem $cut_long_words sogar mitten im Zeichen getrennt werden. Für multibyte-sicheres Umbrechen empfiehlt sich eine dedizierte Bibliothek wie mb_wordwrap() aus symfony/polyfill oder das manuelle Umbrechen an Graphem-Grenzen.
• Der Umbruch-String zählt nicht zur Breite. Die Breite misst nur den ursprünglichen Text, sodass ein langer $break-String (wie "<br />\n") die Zeilen nicht kürzer macht.

Verwandte Funktionen

• nl2br() — HTML-Zeilenumbrüche vor vorhandenen Zeilenumbrüchen einfügen.
• chunk-split() — einen String in gleich lange Stücke aufteilen, unabhängig von Wortgrenzen.
• str-split() — einen String in ein Array mit Teilen fester Länge aufteilen.
• substr() — einen Teil eines Strings extrahieren.
• explode() — einen String anhand eines Trennzeichens in ein Array aufteilen.

Übung