wordwrap
Wraps a string onto multiple lines at a given width, breaking on spaces.
wordwrap(string $string, int $width = 75, string $break = "\n", bool $cut_long_words = false): string- Added in PHP 4.0.2
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The input string. |
$widthoptional | int= 75 | The number of characters at which the string is wrapped. |
$breakoptional | string= "\n" | The string inserted at each break point. Must not be empty. |
$cut_long_wordsoptional | bool= false | When true, words longer than width are split so no line ever exceeds width. When false, such words are left intact and overflow the line. |
Return value
stringThe input string wrapped at the requested width.
Errors
Throws a ValueError if break is an empty string (PHP 8.0.0 and later; earlier versions emitted E_WARNING and returned false).
Changelog
- PHP 8.0.0An empty break string now throws ValueError instead of emitting E_WARNING and returning false.
wordwrap() inserts a break string into text so that no line runs past a given width, splitting only at spaces (U+0020) so words stay whole. It is the standard way to reflow a paragraph for a plain-text email, a terminal, or a fixed-width report.
When to reach for it
Use it for plain-text output that has a hard column limit: RFC-style email bodies at 72 or 78 columns, CLI help text, console tables, or a text file someone will open in a fixed-width editor. Pass <br> as the break string when you need HTML line breaks and the source is a plain string rather than pre-formatted text.
What trips people up
By default a word longer than width is not broken — it simply sticks out past the margin. That is usually the right choice for prose but wrong for content containing long URLs, hashes, or filenames, where you want cut_long_words set to true.
Only the space character is treated as a break opportunity. Tabs, non-breaking spaces, and hyphens are not, so tab-indented text and text pasted from a word processor often wrap in the wrong places. Normalise whitespace first if the input is not under your control.
Example
When to use it
- Reflowing a plain-text email body to 72 columns before sending it.
- Formatting a long product description into fixed-width lines for a terminal table.
- Forcing long URLs and hashes to break so a log file or PDF cell does not overflow.
Frequently asked questions
Why does wordwrap break my UTF-8 text in the wrong place?
wordwrap() measures the string in bytes, so an accented or CJK character counts as two to four. Lines wrap early, and with cut_long_words enabled a character can be split in half. Use a multibyte-safe approach such as preg_replace with the /u modifier for non-ASCII input.
How do I make wordwrap break long words?
Pass true as the fourth argument (cut_long_words). By default it leaves any word longer than the width intact, so that line overflows the margin.
What is the difference between wordwrap and chunk_split?
wordwrap() breaks at spaces so words stay whole; chunk_split() cuts blindly every N bytes regardless of content. Use chunk_split() for encoded data such as base64 and wordwrap() for human-readable text.
More examples
Wrapping with a custom break string
The break parameter is any string, not just a newline. The first call produces HTML line breaks followed by a real newline so the source stays readable; the second builds a quoted-block look by starting each continued line with a pipe. The width still counts only the original characters — the break string itself is not counted toward the next line's length.
<?php
$desc = 'Hand-stitched leather satchel with brass fittings and a lined interior.';
echo wordwrap($desc, 30, "<br>\n"), "\n\n";
echo wordwrap($desc, 30, "\n| "), "\n";cut_long_words on and off
With the default false, the 27-character courier name is kept whole and overflows the 20-column margin. With true, it is split mid-word so every line is at most 20 characters. Use true only when a hard limit matters more than readability, such as filling a fixed-width column.
<?php
$note = 'Order 1042 shipped via ExpressCourierInternational today.';
echo "cut = false\n";
echo wordwrap($note, 20, "\n", false), "\n\n";
echo "cut = true\n";
echo wordwrap($note, 20, "\n", true), "\n";Verifying that no line exceeds the width
Splitting the result back on the break string and measuring each line proves the guarantee: with cut_long_words true, every reported length is 18 or less. Run the same check with false and any word longer than 18 characters produces a line over the limit.
<?php
$text = 'alpha beta gamma delta epsilon zeta eta theta iota kappa';
$wrapped = wordwrap($text, 18, "\n", true);
foreach (explode("\n", $wrapped) as $i => $line) {
printf("%d: %-18s (%d)\n", $i, $line, strlen($line));
}
Discussion