Un champ de réglage personnalisé qui accepte une couleur au format texte libre, sans validation, finit tôt ou tard par recevoir une valeur inattendue : un nom de couleur CSS, une chaîne rgba, ou simplement une faute de frappe. Si cette valeur est ensuite injectée directement dans une feuille de style générée dynamiquement, le résultat peut aller d’un style silencieusement ignoré à une chaîne CSS mal formée qui casse l’affichage.
sanitize_hex_color() répond à ce besoin précis de validation, en acceptant uniquement une chaîne conforme au format hexadécimal court ou long, précédée d’un dièse.
Ce que la fonction accepte, et ce qu’elle rejette
sanitize_hex_color( '#ff6600' ); // '#ff6600'
sanitize_hex_color( '#f60' ); // '#f60'
sanitize_hex_color( 'ff6600' ); // null (dièse manquant)
sanitize_hex_color( 'orange' ); // null (pas un format hexadécimal)
sanitize_hex_color( '' ); // '' (chaîne vide autorisée telle quelle)
Une valeur vide est traitée à part : elle est retournée telle quelle, sans être considérée comme invalide, ce qui permet à un champ de réglage de rester facultatif sans déclencher de rejet sur une valeur simplement non renseignée.
Utilisation dans un callback de réglage
register_setting( 'mon_groupe_reglages', 'ma_couleur_accent', array(
'type' => 'string',
'sanitize_callback' => 'sanitize_hex_color',
'default' => '#2271b1',
) );
En le déclarant directement comme sanitize_callback, chaque enregistrement du réglage passe automatiquement par cette validation, sans code supplémentaire à écrire dans le formulaire d’administration lui-même.
La variante sans dièse
Pour un champ où le dièse est ajouté séparément à l’affichage plutôt que saisi par l’utilisateur, sanitize_hex_color_no_hash() accepte le même format sans exiger le caractère # en préfixe, et retourne la valeur également sans dièse.
| Fonction | Format attendu en entrée | Format en sortie |
|---|---|---|
sanitize_hex_color() | Avec dièse | Avec dièse, ou null |
sanitize_hex_color_no_hash() | Sans dièse | Sans dièse, ou null |
Ce que cette fonction ne couvre pas
- Les formats rgb(), rgba() ou hsl() ne sont pas reconnus par cette fonction : elle est strictement dédiée au format hexadécimal.
- Elle ne gère aucune conversion entre formats : une valeur rgba() valide sera simplement rejetée, jamais convertie automatiquement.
- Pour les palettes de couleurs déclarées dans
theme.json, la validation suit un mécanisme différent, propre au schéma de ce fichier, sans passer par cette fonction PHP.
Un repère pour toute page de réglages personnalisée qui propose un champ de couleur : dès que ce champ n’est pas un composant natif de sélection de couleur, une validation explicite via
sanitize_hex_color()évite qu’une valeur mal formée ne remonte jusqu’à une feuille de style générée dynamiquement.
En résumé
Un champ de couleur en apparence anodin mérite la même rigueur de validation que n’importe quel autre champ de réglage. sanitize_hex_color() couvre le cas le plus courant — un format hexadécimal — avec un comportement prévisible : une valeur conforme passe, tout le reste devient null, sans jamais laisser passer une chaîne à moitié valide.
