wordwrap()

Introduzione

La funzione wordwrap() in PHP manda a capo una stringa su più righe in modo che nessuna riga superi una larghezza specificata. Scorre la stringa e inserisce un'interruzione di riga all'ultimo spazio prima che il limite venga raggiunto, in modo da mantenere le parole intere. Questo è utile per formattare output in testo semplice — email, file di log, messaggi console, o qualsiasi contesto in cui si necessiti di una larghezza di colonna fissa senza poter utilizzare CSS per il ritorno a capo.

Sintassi

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

La funzione restituisce una nuova stringa — non modifica l'originale. Si noti che wordwrap() manda a capo sugli spazi, non sui confini delle parole in generale; una lunga sequenza di caratteri senza spazi viene interrotta solo quando $cut_long_words è true.

Esempio di base

Manda a capo una frase a 20 caratteri:

Output:

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

Nessuna riga supera i 20 caratteri. Ogni interruzione sostituisce lo spazio all'ultimo confine di parola che rientra nel limite, quindi le parole non vengono mai spezzate.

Ritorno a capo per HTML con un'interruzione personalizzata

L'argomento $break può essere qualsiasi stringa, non solo una nuova riga. Per mandare a capo il testo all'interno di HTML, usa un tag <br /> (combinato con \n per mantenere leggibile il sorgente):

<?php

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

Output:

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

Se il tuo obiettivo è semplicemente convertire le nuove righe esistenti in tag <br>, usa nl2br() — wordwrap() serve per creare le interruzioni di riga, nl2br() per convertirle.

Taglio delle parole lunghe

Per impostazione predefinita, una parola più lunga di $width viene lasciata intera e supera il margine della riga. Passa true come quarto argomento per forzare la funzione a spezzare le parole lunghe:

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

Output:

Default (no cut):
Supercalifragilisticexpialidocious

With cut:
Supercalif
ragilistic
expialidoc
ious

Usa l'opzione di taglio per contenuti che devono rispettare un limite di colonna fisso — ad esempio output terminale a larghezza fissa o URL che altrimenti supererebbero il margine.

Problemi comuni

• Le nuove righe esistenti non vengono normalizzate. wordwrap() conta i caratteri tra i punti di interruzione; non ridispone il testo che contiene già le proprie interruzioni di riga. Se necessario, ripulisci prima l'input.
• La larghezza è in byte, non in caratteri. Come la maggior parte delle funzioni classiche per le stringhe in PHP, wordwrap() è basata sui byte. I caratteri multibyte (UTF-8) possono quindi essere conteggiati in modo errato e possono persino essere spezzati a metà quando $cut_long_words è true. Per un ritorno a capo sicuro con caratteri multibyte, usa una libreria dedicata come mb_wordwrap() di symfony/polyfill oppure gestisci tu stesso il ritorno a capo sui confini dei grafemi.
• La stringa di interruzione non viene conteggiata nella larghezza. La larghezza misura solo il testo originale, quindi un $break lungo (come "<br />\n") non accorcerà le tue righe.

Funzioni correlate

• nl2br() — inserisce interruzioni di riga HTML prima delle nuove righe esistenti.
• chunk-split() — divide una stringa in blocchi di lunghezza uguale indipendentemente dai confini delle parole.
• str-split() — suddivide una stringa in un array di pezzi a lunghezza fissa.
• substr() — estrae una porzione di una stringa.
• explode() — divide una stringa in un array usando un delimitatore.

Pratica