wordwrap()

Purpose

wordwrap() takes a string and inserts a break sequence so that lines stay near a chosen number of characters. It is a plain-text tool: it suits email bodies, console output, fixed-width reports and captions where you control the line length. It returns a new string and leaves the original untouched.

By default the function only breaks at spaces (U+0020). It never splits a word unless you explicitly ask it to.

Signature

Parameters and defaults

• $string: the text to wrap.
• $width: the number of characters at which the text is wrapped. The default is 75.
• $break: the string inserted at each wrap point. The default is a single newline, "\n". It must not be empty.
• $cut_long_words: when false (the default), a word longer than the width stays whole, so that line can be longer than $width. When true, the result is always wrapped at or before the width, and oversized words are split.

Return value and failure cases

The function returns the wrapped string. Since PHP 8.0, passing an empty string as $break throws a ValueError. Earlier versions emitted a warning and returned false, so code written for PHP 7 that checks for false no longer applies. In PHP 8.4 the return type is simply string.

Example 1: basic wrapping

This wraps a sentence at 20 characters with the default newline break. The first line, The quick brown fox, is 19 characters, and adding the next word would pass 20. The second line is exactly 20 characters and still fits.

<?php
$text = "The quick brown fox jumped over the lazy dog.";
echo json_encode(wordwrap($text, 20, "\n"), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

"The quick brown fox\njumped over the lazy\ndog."

Example 2: long words and cut_long_words

A word that does not fit the width is handled differently depending on the fourth argument. Here the word extraordinary has 13 letters and the width is 5.

<?php
$text = "go extraordinary now";
$kept = wordwrap($text, 5, "\n", false);
$cut = wordwrap($text, 5, "\n", true);
echo json_encode([$kept, $cut], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

["go\nextraordinary\nnow","go\nextra\nordin\nary\nnow"]

With false, the long word gets its own line and keeps its full length. With true, it is cut into pieces of at most five characters.

Example 3: an empty break is rejected

Because an empty break makes no sense as a line separator, PHP 8 throws an exception. You can catch it as ValueError.

<?php
try {
    wordwrap("abc", 5, "");
} catch (ValueError $e) {
    echo get_class($e), "\n";
}

ValueError

Edge cases

• Long words without cutting: with the default $cut_long_words = false, a long URL or identifier stays on one line, even if it is far wider than $width. Do not assume every line is at most $width characters unless you pass true.
• Custom break strings: $break may be any non-empty string, for example "<br />\n" for HTML output or "\r\n" for protocols that need CRLF. The width counts only the text, not the break you insert.
• Characters are bytes: wordwrap() is a byte-oriented string function. For multibyte text such as UTF-8 with accented letters or emoji, the width is not a count of visible characters, and cutting long words can split a character. Choose another approach for multibyte layout.
• Only spaces are break opportunities: the manual describes wrapping after a space character. Hyphens and tabs are not treated as places to wrap.

Common mistakes

1. Expecting a hard maximum line length without setting $cut_long_words to true.
2. Passing the arguments in the wrong order, such as putting the break before the width. The order is string, width, break, cut.
3. Using "\n" in single quotes. In '\n' the characters are a backslash and the letter n, not a newline. Use double quotes for escape sequences.
4. Writing HTML-bound text with "\n" and expecting the browser to show line breaks. HTML collapses whitespace, so use <br /> as the break, or convert newlines afterwards with nl2br().
5. Passing an empty break and checking for false. In PHP 8 this throws instead.

Related functions

• nl2br() inserts HTML line breaks before newlines in a string, which pairs well with wordwrap() for browser output.
• chunk_split() splits a string into chunks of a fixed length, regardless of word boundaries.

Recap

wordwrap() inserts a break string at spaces so lines stay within a width, defaulting to 75 characters and a newline. Set the fourth argument to true to split words longer than the width. An empty break throws a ValueError in PHP 8, and widths are measured in bytes, not visible characters.