Couper une chaîne de texte à un nombre de caractères fixe avec substr() semble simple, jusqu’au jour où la coupe tombe en plein milieu d’un mot, ou pire, en plein milieu d’une balise HTML restée ouverte. Le rendu de la page se retrouve alors cassé, parfois de façon visible seulement sur certains navigateurs plus stricts dans leur correction d’erreurs.
wp_trim_words() évite ce problème en coupant à un nombre de mots précis plutôt qu’à un nombre de caractères, et en supprimant les balises HTML avant d’effectuer la coupe.
Signature et comportement
wp_trim_words( $text, $num_words = 55, $more = null ) : le premier argument est le texte source, le second le nombre de mots à conserver, le troisième le texte ajouté à la fin si une coupe a effectivement eu lieu — par défaut, une ellipse HTML.
$texte = '<p>Ce texte contient plusieurs <strong>mots importants</strong> à conserver.</p>';
$resume = wp_trim_words( $texte, 5, '…' );
// Ce texte contient plusieurs mots…
Les balises <p> et <strong> disparaissent du résultat : wp_trim_words() travaille sur le texte brut, sans HTML, ce qui garantit qu’aucune balise ne peut rester ouverte après la coupe.
Un usage typique : un résumé personnalisé sur une archive
function afficher_resume_court() {
$contenu = get_post_field( 'post_content', get_the_ID() );
echo wp_trim_words( $contenu, 20, '<a href="' . esc_url( get_permalink() ) . '">Lire la suite</a>' );
}
Ce genre de résumé, plus court que l’extrait automatique par défaut, convient bien à une grille de vignettes où l’espace disponible est limité et où un extrait de cinquante-cinq mots serait trop long visuellement.
Différence avec l’extrait automatique
| Fonction | Unité de coupe | Comportement HTML |
|---|---|---|
wp_trim_words() | Nombre de mots | Retire toutes les balises avant la coupe |
substr() brut | Nombre de caractères | Aucune gestion du HTML, risque de balise cassée |
wp_trim_excerpt() | Nombre de mots (via le filtre excerpt_length) | Applique en plus les filtres d’extrait standard |
Un piège lié aux langues sans espaces
- La coupe par mots de
wp_trim_words()repose sur la présence d’espaces entre les mots, un principe qui ne s’applique pas de la même façon à toutes les langues. - Le filtre
wp_trim_wordspermet d’adapter le comportement si un site multilingue en a besoin, sans modifier le cœur de la fonction. - Le nombre de mots demandé est indicatif : un texte plus court que ce nombre est retourné intégralement, sans texte de fin ajouté.
Un repère simple pour choisir entre les deux fonctions :
wp_trim_words()pour un résumé personnalisé affiché en dehors du flux normal du contenu,wp_trim_excerpt()ou l’extrait natif dès que la cohérence avec le comportement standard des extraits WordPress est recherchée.
En résumé
Un substr() brut sur du contenu HTML est une source récurrente de balises cassées, invisible tant qu’un test suffisamment long n’a pas été effectué. wp_trim_words() règle ce problème une fois pour toutes en coupant au mot près et en retirant systématiquement le HTML avant la coupe, un remplacement simple pour tout code qui tronque encore du contenu à la main.
