wordwrap()

Введение

Функция wordwrap() в PHP переносит строку на несколько строк так, чтобы ни одна из них не превышала заданную ширину. Она обходит строку и вставляет разрыв строки на последнем пробеле до достижения лимита, чтобы слова оставались нетронутыми. Это удобно для форматирования вывода в виде обычного текста — писем, файлов журналов, сообщений консоли или любых мест, где нужна фиксированная ширина столбца без CSS-переноса.

Синтаксис

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

Функция возвращает новую строку — исходная строка не изменяется. Обратите внимание, что wordwrap() переносит по пробелам, а не по границам слов в общем смысле; длинная последовательность символов без пробелов разрывается только при $cut_long_words равном true.

Простой пример

Перенос предложения по 20 символов:

Вывод:

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

Ни одна строка не превышает 20 символов. Каждый разрыв заменяет пробел на последней границе слова, умещающейся в лимит, поэтому слова никогда не разрываются.

Перенос для HTML с пользовательским разрывом

Аргумент $break может быть любой строкой, а не только символом новой строки. Для переноса текста в HTML используйте тег <br /> (вместе с \n, чтобы исходный код оставался читаемым):

<?php

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

Вывод:

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

Если вам нужно просто преобразовать существующие символы новой строки в теги <br>, используйте nl2br() — wordwrap() предназначена для создания разрывов строк, а nl2br() — для их преобразования.

Разрезание длинных слов

По умолчанию слово длиннее $width остаётся целым и выходит за пределы строки. Передайте true в качестве четвёртого аргумента, чтобы функция принудительно разрывала длинные слова:

<?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);

Вывод:

Default (no cut):
Supercalifragilisticexpialidocious

With cut:
Supercalif
ragilistic
expialidoc
ious

Используйте опцию разрезания для содержимого, которое должно строго соблюдать ширину столбца, — например, для вывода в терминале фиксированной ширины или URL, которые иначе выйдут за поля.

Частые подводные камни

• Существующие символы новой строки не нормализуются. wordwrap() считает символы между точками переноса; она не перераспределяет текст, в котором уже есть собственные переносы строк. При необходимости сначала очистите входные данные.
• Ширина измеряется в байтах, а не в символах. Как и большинство классических строковых функций PHP, wordwrap() работает побайтово. Многобайтовые символы (UTF-8) могут быть неправильно подсчитаны и даже разорваны посередине при $cut_long_words равном true. Для многобайтового переноса используйте специализированную библиотеку, например mb_wordwrap() из symfony/polyfill, или самостоятельно переносите по границам графем.
• Строка разрыва не учитывается в ширине. Ширина измеряется только по исходному тексту, поэтому длинный $break (например, "<br />\n") не укоротит ваши строки.

Связанные функции

• nl2br() — вставляет HTML-разрывы строк перед существующими символами новой строки.
• chunk-split() — разбивает строку на фрагменты равной длины без учёта границ слов.
• str-split() — разбивает строку на массив частей фиксированной длины.
• substr() — извлекает часть строки.
• explode() — разбивает строку на массив по разделителю.

Практика