wordwrap()

Introduction

La fonction wordwrap() en PHP enveloppe une chaîne sur plusieurs lignes de sorte qu'aucune ligne ne dépasse une largeur donnée. Elle parcourt la chaîne et insère un saut de ligne au dernier espace avant que la limite soit atteinte, afin que les mots restent entiers. Ceci est utile pour formater du texte brut — e-mails, fichiers journaux, messages en console, ou tout endroit où vous avez besoin d'une largeur de colonne fixe sans CSS pour gérer le retour à la ligne.

Syntaxe

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

La fonction retourne une nouvelle chaîne — elle ne modifie pas l'original. Notez que wordwrap() enveloppe sur les espaces, et non sur les limites de mots en général ; une longue séquence de caractères sans espace n'est découpée que lorsque $cut_long_words est true.

Exemple de base

Envelopper une phrase à 20 caractères :

Résultat :

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

Aucune ligne ne dépasse 20 caractères. Chaque coupure remplace l'espace à la dernière limite de mot qui tient dans la limite, de sorte que les mots ne sont jamais découpés.

Envelopper pour HTML avec un saut personnalisé

L'argument $break peut être n'importe quelle chaîne, pas seulement un saut de ligne. Pour envelopper du texte dans HTML, utilisez une balise <br /> (combinée avec \n pour que le code source reste lisible) :

<?php

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

Résultat :

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

Si votre objectif est simplement de convertir les sauts de ligne existants en balises <br>, utilisez plutôt nl2br() — wordwrap() sert à créer les sauts de ligne, nl2br() sert à les convertir.

Découper les mots longs

Par défaut, un mot plus long que $width est laissé entier et déborde de la ligne. Passez true comme quatrième argument pour forcer la fonction à couper à l'intérieur des mots longs :

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

Résultat :

Default (no cut):
Supercalifragilisticexpialidocious

With cut:
Supercalif
ragilistic
expialidoc
ious

Utilisez l'option de découpage pour les contenus qui doivent respecter une limite de colonne stricte — par exemple une sortie terminal en largeur fixe ou des URL qui dépasseraient sinon la marge.

Pièges courants

• Les sauts de ligne existants ne sont pas normalisés. wordwrap() compte les caractères entre les points de coupure ; elle ne re-formate pas le texte qui contient déjà ses propres sauts de ligne. Nettoyez l'entrée au préalable si nécessaire.
• La largeur est en octets, pas en caractères. Comme la plupart des fonctions de chaînes classiques de PHP, wordwrap() est basée sur les octets. Les caractères multi-octets (UTF-8) peuvent donc être mal comptés et même être découpés en plein milieu lorsque $cut_long_words est true. Pour un retour à la ligne sûr en multi-octets, utilisez une bibliothèque dédiée comme mb_wordwrap() de symfony/polyfill ou gérez vous-même les limites de graphèmes.
• La chaîne de saut ne compte pas. La largeur mesure uniquement le texte original, donc un $break long (comme "<br />\n") ne raccourcira pas vos lignes.

Fonctions associées

• nl2br() — insère des sauts de ligne HTML avant les sauts de ligne existants.
• chunk-split() — divise une chaîne en morceaux de longueur égale sans tenir compte des limites de mots.
• str-split() — décompose une chaîne en un tableau de morceaux de longueur fixe.
• substr() — extrait une portion d'une chaîne.
• explode() — divise une chaîne en tableau selon un délimiteur.

Pratique