Un bloc qui affiche un champ de formulaire, répété plusieurs fois sur la même page, a besoin d’un identifiant HTML différent à chaque occurrence pour relier correctement une balise label à son champ via l’attribut for. Un identifiant codé en dur dans le rendu du bloc casserait cette relation dès la seconde occurrence sur la page.
wp_unique_id() répond à ce besoin précis : elle génère, à chaque appel, une chaîne garantie différente de toutes les précédentes générées dans la même requête, sans que le développeur ait à gérer lui-même un compteur global.
Signature et fonctionnement
wp_unique_id( $prefix = '' ) accepte un préfixe optionnel, suivi d’un nombre entier incrémenté en interne à chaque appel. Sans préfixe, l’identifiant retourné est simplement ce nombre sous forme de chaîne.
function render_mon_bloc_champ( $attributes ) {
$id_champ = wp_unique_id( 'mon-bloc-champ-' );
return sprintf(
'<label for="%1$s">%2$s</label><input type="text" id="%1$s" />',
esc_attr( $id_champ ),
esc_html( $attributes['label'] )
);
}
Chaque appel à render_mon_bloc_champ() produit un identifiant différent, même si le bloc apparaît plusieurs fois sur la même page, sans qu’aucune variable globale ou statique n’ait besoin d’être déclarée dans le code du bloc.
Pourquoi pas un compteur statique fait maison
function ancien_generateur_id( $prefix = '' ) {
static $compteur = 0;
$compteur++;
return $prefix . $compteur;
}
Cette approche fonctionne isolément, mais devient fragile dès que plusieurs blocs ou extensions utilisent chacun leur propre compteur statique : rien ne garantit qu’un préfixe partagé entre deux composants différents ne produise pas, par coïncidence, le même identifiant final. wp_unique_id() centralise ce compteur au niveau de WordPress lui-même, partagé par tout le code qui l’utilise sur la même requête.
Cas d’usage typiques
- Relier un
labelà un champ dans un bloc réutilisable, répété plusieurs fois sur une même page. - Générer un identifiant d’ancre unique pour un accordéon ou un onglet affiché en plusieurs exemplaires.
- Associer un attribut
aria-describedbyà un message d’aide contextuel, dans un composant destiné à être inséré plusieurs fois.
Ce que la fonction ne garantit pas
L’unicité garantie par wp_unique_id() porte sur la requête PHP courante, pas sur des identifiants persistés entre deux chargements de page distincts. Pour un identifiant qui doit rester stable d’un chargement à l’autre — par exemple un identifiant enregistré en base de données — cette fonction n’est pas l’outil adapté ; elle sert uniquement à distinguer plusieurs occurrences dans un même rendu HTML.
Un repère utile pour le développement de blocs réutilisables : dès qu’un identifiant HTML est généré à l’intérieur d’une fonction de rendu, il doit passer par
wp_unique_id()plutôt que par une valeur fixe, même si le bloc semble, au moment de l’écriture, destiné à n’apparaître qu’une seule fois par page.
En résumé
Écrire un compteur statique maison pour générer des identifiants uniques est une solution qui a longtemps semblé suffisante, jusqu’à ce que plusieurs composants indépendants entrent en collision sur le même préfixe. wp_unique_id() centralise ce besoin dans une fonction unique, partagée par tout le code d’un site, blocs et extensions confondus.
