« class= »ouvert » onclick= »alert(1) » » — une chaîne d’attribut de ce type, reconstruite à la main à partir d’une saisie utilisateur avant d’être injectée dans une balise générée dynamiquement, illustre exactement le problème que wp_kses_one_attr() a été conçue pour résoudre. Beaucoup de développeurs, n’ayant jamais entendu parler de cette fonction, réinventent une sanitisation partielle avec str_replace() ou une expression régulière personnalisée, ce qui laisse presque toujours passer un cas limite que l’auteur n’avait pas anticipé.
Un besoin plus étroit que wp_kses()
wp_kses(), largement connue, traite un document HTML entier : elle parcourt chaque balise, chaque attribut, et ne conserve que ce qui figure dans la liste blanche fournie. Ce fonctionnement est parfaitement adapté quand on dispose d’un bloc de contenu HTML complet à nettoyer. Le problème se pose différemment quand une extension ne manipule qu’un seul attribut isolé — par exemple une valeur de style ou de data-* reconstruite dans le cadre d’un composant généré dynamiquement — sans jamais construire un document HTML complet autour.
wp_kses_one_attr() répond précisément à ce cas plus étroit. Sa signature prend une chaîne d’attribut complète (nom et valeur, au format attribut="valeur") et le nom de l’élément HTML auquel cet attribut est destiné :
$attribut_propre = wp_kses_one_attr( 'href="javascript:alert(1)"', 'a' );
// $attribut_propre est vide : javascript: est retiré du protocole autorisé.
$attribut_propre = wp_kses_one_attr( 'href="https://exemple.test/page"', 'a' );
// $attribut_propre reste intact : le protocole est autorisé.Le second paramètre, le nom de l’élément, n’est pas décoratif : certains attributs ne sont valides que pour certaines balises selon la liste blanche interne de WordPress (rel et target pour a, par exemple), et la fonction en tient compte pour décider si l’attribut doit être conservé.
Le cas concret : un attribut reconstruit sans passer par un document complet
Une extension qui génère un élément d’interface personnalisé, par exemple une balise construite à partir d’un enregistrement stocké en base, peut avoir besoin de nettoyer un attribut style composé dynamiquement à partir de plusieurs valeurs saisies dans un formulaire d’administration :
function construire_attribut_style( $couleur, $taille ) {
$brut = sprintf( 'style="color:%s;font-size:%spx"', $couleur, $taille );
return wp_kses_one_attr( $brut, 'span' );
}
$style_sanitise = construire_attribut_style( $couleur_saisie, $taille_saisie );
echo '<span ' . $style_sanitise . '>Texte</span>';Sans cette étape, une valeur de couleur contenant une séquence CSS malveillante (une expression url() pointant vers une ressource externe non désirée, par exemple) passerait telle quelle dans le HTML généré. Reconstruire un filtre équivalent à la main obligerait à connaître précisément les mêmes règles que celles déjà encodées dans cette fonction interne — un travail redondant et sujet à erreur.
Une fonction techniquement interne, mais publiquement appelable
wp_kses_one_attr() est déclarée dans wp-includes/kses.php et utilisée en interne par wp_kses() pour traiter chaque attribut rencontré lors du parcours d’un document complet. Elle reste néanmoins une fonction publique, sans préfixe d’espace de noms privé ni avertissement de dépréciation, ce qui la rend légitimement appelable directement depuis le code d’une extension. La documentation officielle la présente cependant avec moins de mise en avant que wp_kses() ou wp_kses_post(), ce qui explique pourquoi elle reste peu connue en dehors des cas où un développeur a dû lire le code source de wp_kses() pour comprendre son fonctionnement interne.
Une fonction qui existe déjà dans le cœur pour résoudre exactement le problème posé vaut toujours mieux qu’une expression régulière écrite à la hâte pour le même besoin.
Ce qu’elle ne fait pas
wp_kses_one_attr() attend une chaîne d’attribut complète, pas seulement une valeur brute : lui passer directement une valeur de couleur sans l’encadrer du nom d’attribut produirait un résultat incohérent, puisque la fonction s’attend à reconnaître un nom d’attribut suivi d’un signe égal. Elle ne traite pas non plus plusieurs attributs à la fois : chaque appel correspond à un seul attribut sur un seul élément. Pour nettoyer plusieurs attributs simultanément, il faut soit appeler la fonction autant de fois que nécessaire, soit revenir à wp_kses() sur un fragment HTML complet si le nombre d’attributs à traiter devient important.
La distinction avec wp_kses_post()
wp_kses_post() applique une liste blanche déjà configurée, celle des balises autorisées dans le contenu d’un article, à un document HTML entier — un usage complémentaire mais distinct de celui de wp_kses_one_attr(), qui ne prend pas de liste blanche de balises en paramètre puisqu’elle ne travaille que sur un attribut isolé. Cette différence de granularité n’est volontairement pas développée davantage ici, wp_kses_post() répondant à un besoin d’un tout autre ordre : celui du contenu complet d’un article plutôt que d’un attribut ponctuel.
- Réserver wp_kses_one_attr() aux cas où seul un attribut isolé doit être nettoyé.
- Toujours fournir le nom de l’élément HTML réel auquel l’attribut est destiné.
- Préférer wp_kses() dès qu’un document HTML complet doit être traité.
- Ne jamais reconstruire une sanitisation d’attribut personnalisée quand cette fonction couvre déjà le besoin.
wp_kses_one_attr() occupe une niche précise entre l’échappement générique (esc_attr()) et le traitement complet d’un document (wp_kses()). Elle mérite d’être connue dès qu’une extension construit dynamiquement un attribut HTML à partir d’une donnée qui n’a pas transité par un contexte déjà sécurisé.
