Avant WordPress 6.2, ajouter une classe CSS à toutes les images d’un contenu généré par des blocs relevait souvent du bricolage : une expression régulière du type preg_replace( '/<img /', '<img class="ma-classe" ', $html ), qui fonctionne tant que le HTML est parfaitement prévisible et casse dès qu’un attribut contient déjà une classe, ou dès qu’un attribut porte un caractère spécial mal anticipé. On a tous une anecdote de production cassée par un guillemet imprévu dans un attribut alt.
WordPress 6.2 a résolu ce problème à la racine avec WP_HTML_Tag_Processor, une classe qui parcourt un fragment HTML balise par balise et permet de lire ou modifier ses attributs sans jamais construire un DOM complet ni recourir à une bibliothèque externe comme DOMDocument. C’est plus léger, plus rapide, et surtout beaucoup plus fiable qu’une regex sur du HTML arbitraire.
Le principe : un curseur, pas un arbre
Contrairement à DOMDocument, qui charge l’intégralité du document en mémoire sous forme d’arbre, WP_HTML_Tag_Processor fonctionne comme un curseur qui avance séquentiellement dans la chaîne de caractères. On appelle next_tag() pour se positionner sur la balise suivante correspondant à un critère, puis on lit ou modifie ses attributs avant de continuer. Cette approche évite le coût de construction d’un arbre complet, un point important quand on traite le contenu de chaque article à l’affichage via un filtre the_content.
Ajouter une classe et un attribut
Le cas d’usage le plus courant pour un auteur d’extension : ajouter une classe CSS ou un attribut de données à certaines balises générées par des blocs, sans toucher au balisage du bloc lui-même. Exemple pour ajouter loading="lazy" et une classe utilitaire à toutes les images d’un contenu :
function mon_extension_enrichir_images( $contenu ) {
$processeur = new WP_HTML_Tag_Processor( $contenu );
while ( $processeur->next_tag( 'img' ) ) {
$processeur->set_attribute( 'loading', 'lazy' );
$processeur->add_class( 'mon-extension-image' );
}
return $processeur->get_updated_html();
}
add_filter( 'the_content', 'mon_extension_enrichir_images' );
La méthode next_tag() accepte aussi un tableau de critères pour cibler précisément une balise selon son nom, sa classe existante, ou d’autres attributs :
$processeur->next_tag( array(
'tag_name' => 'a',
'class_name' => 'wp-block-button__link',
) );
Cibler un bloc précis dans du contenu généré
Un cas fréquent pour une extension qui enrichit les blocs natifs : ajouter un attribut data-analytics uniquement sur les liens des blocs bouton, sans toucher aux autres liens du contenu. Le tag processor permet cette précision sans jamais parser le commentaire de bloc lui-même :
function mon_extension_tracer_boutons( $contenu, $bloc ) {
if ( 'core/button' !== $bloc['blockName'] ) {
return $contenu;
}
$processeur = new WP_HTML_Tag_Processor( $contenu );
if ( $processeur->next_tag( 'a' ) ) {
$processeur->set_attribute( 'data-analytics', 'bouton-cta' );
}
return $processeur->get_updated_html();
}
add_filter( 'render_block', 'mon_extension_tracer_boutons', 10, 2 );
Ce que l’API ne fait pas (encore)
Il faut être honnête sur les limites de la version introduite en 6.2 : elle permet de lire et modifier des attributs, mais pas de restructurer l’arbre HTML (déplacer une balise, en insérer une nouvelle entre deux autres, ou changer le nom d’une balise). Pour ces besoins, il faut encore passer par une reconstruction manuelle de chaîne ou par DOMDocument. Des versions ultérieures de WordPress ont progressivement enrichi les capacités de navigation dans l’arbre (profondeur, balises fermantes), mais la version 6.2 reste centrée sur la lecture et la modification d’attributs balise par balise.
Comparaison avec les approches précédentes
- Expressions régulières : rapides à écrire, mais fragiles dès que le HTML n’est pas parfaitement homogène (attributs entre guillemets simples, espaces multiples, attributs booléens sans valeur).
- DOMDocument : robuste et complet, mais plus lourd en mémoire et en temps de traitement, et sujet à des surprises d’encodage si l’on ne configure pas correctement le chargement en UTF-8.
- WP_HTML_Tag_Processor : le bon compromis pour des modifications ciblées d’attributs sur du HTML de blocs, avec une API pensée nativement pour WordPress.
Notre règle sur les projets récents : dès qu’une modification se limite à des attributs (classe, style inline, data-*, aria-*), on utilise le tag processor. Dès qu’il faut restructurer le HTML en profondeur, on garde DOMDocument en réserve.
Attention aux appels multiples sur le même contenu
Un piège de débutant : instancier plusieurs WP_HTML_Tag_Processor en cascade sur le même filtre, un par type de modification. Chaque instanciation reparcourt l’intégralité du contenu depuis le début. Sur un article long avec beaucoup de blocs, mieux vaut regrouper toutes les modifications dans une seule boucle while ( $processeur->next_tag() ) avec des conditions internes, plutôt que multiplier les passages.
En résumé
WP_HTML_Tag_Processor comble un vrai manque de l’écosystème WordPress : une façon fiable et légère de modifier des attributs HTML sans les pièges des expressions régulières ni le poids d’un DOM complet. Pour toute extension qui enrichit le rendu des blocs — ajout de classes, d’attributs d’accessibilité, de données de tracking — c’est désormais l’outil à privilégier depuis WordPress 6.2, en réservant DOMDocument aux restructurations plus profondes du balisage.
