wordwrap()

Introdução

A função wordwrap() no PHP quebra uma string em múltiplas linhas de forma que nenhuma linha exceda uma largura determinada. Ela percorre a string e insere uma quebra de linha no último espaço antes de atingir o limite, mantendo as palavras intactas. Isso é útil para formatar saída em texto simples — e-mails, arquivos de log, mensagens no console ou qualquer lugar onde você precise de uma largura de coluna fixa e não tenha CSS para fazer a quebra automática.

Sintaxe

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

A função retorna uma nova string — ela não modifica o original. Note que wordwrap() quebra nos espaços, não em limites de palavras em geral; uma longa sequência de caracteres sem espaço só é quebrada quando $cut_long_words é true.

Exemplo básico

Quebrar uma frase em 20 caracteres:

Saída:

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

Nenhuma linha excede 20 caracteres. Cada quebra substitui o espaço no último limite de palavra que cabe dentro do limite, portanto as palavras nunca são divididas.

Quebra para HTML com uma quebra personalizada

O argumento $break pode ser qualquer string, não apenas uma nova linha. Para quebrar texto dentro de HTML, use uma tag <br /> (combinada com \n para que o código-fonte fique legível):

<?php

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

Saída:

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

Se o seu objetivo é simplesmente converter novas linhas existentes em tags <br>, use nl2br() — wordwrap() é para criar as quebras de linha, enquanto nl2br() é para convertê-las.

Cortando palavras longas

Por padrão, uma palavra maior que $width é mantida inteira e ultrapassa a linha. Passe true como quarto argumento para forçar a função a quebrar dentro de palavras longas:

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

Saída:

Default (no cut):
Supercalifragilisticexpialidocious

With cut:
Supercalif
ragilistic
expialidoc
ious

Use a opção de corte para conteúdo que deve respeitar um limite rígido de coluna — por exemplo, saída de terminal de largura fixa ou URLs que de outra forma ultrapassariam a margem.

Armadilhas comuns

• Novas linhas existentes não são normalizadas. wordwrap() trata os caracteres entre pontos de quebra por contagem; ela não reformata texto que já contém suas próprias quebras de linha. Limpe a entrada primeiro, se necessário.
• A largura é em bytes, não em caracteres. Como a maioria das funções de string clássicas do PHP, wordwrap() é baseada em bytes. Caracteres multibyte (UTF-8) podem, portanto, ser contados incorretamente e até divididos no meio quando $cut_long_words é true. Para quebra segura com multibyte, use uma biblioteca dedicada como mb_wordwrap() do symfony/polyfill ou faça a quebra nos limites de grafemas você mesmo.
• A string de quebra não conta para nada. A largura mede apenas o texto original, portanto um $break longo (como "<br />\n") não vai encurtar suas linhas.

Funções relacionadas

• nl2br() — insere quebras de linha HTML antes das novas linhas existentes.
• chunk-split() — divide uma string em partes de comprimento igual, independentemente dos limites das palavras.
• str-split() — divide uma string em um array de partes de comprimento fixo.
• substr() — extrai uma parte de uma string.
• explode() — divide uma string em um array por um delimitador.

Prática