get_theme_mod()

Définition : get_theme_mod() récupère une valeur de personnalisation enregistrée pour le thème WordPress actif. Cette fonction sert notamment à consulter les réglages gérés historiquement par l’API de personnalisation.

Terminologie

Nom technique : get_theme_mod()

Appellations : Nom principal utilisé

À quoi cela sert, concrètement

Elle permet d’adapter un détail visuel comme une couleur, une option d’en-tête ou un texte de présentation sans modifier une constante PHP du thème.

Fonctionnement détaillé

WordPress consulte les modifications de thème sauvegardées et renvoie la valeur associée à une clé ou une valeur par défaut lorsqu’aucun réglage correspondant n’a été trouvé.

Quand l’utiliser : contexte et choix techniques

L’utiliser pour les thèmes qui exploitent les réglages du Customizer ou des theme mods. Dans un thème à blocs, évaluer d’abord les styles globaux avant d’ajouter un système parallèle de personnalisation.

Situation professionnelle réaliste

Un thème classique possède une couleur d’accent enregistrée sous atoolpha_accent et souhaite l’appliquer seulement si elle constitue une couleur hexadécimale admissible.

Exemple pratique — PHP commenté

Exemple pédagogique : adapter le nom du thème, les fichiers et les conditions à un environnement de développement. Il ne constitue pas une preuve d’exécution sur ATOOLPHA.

<?php
$accent = get_theme_mod( 'atoolpha_accent', '#245A81' );
$valid  = sanitize_hex_color( $accent );
if ( $valid ) {
    // Valeur préparée pour une règle CSS contrôlée.
    echo '<span style="color:' . esc_attr( $valid ) . '">';
    echo 'Texte d’exemple';
    echo '</span>';
}

Décryptage de l’exemple, étape par étape

Le premier appel lit le réglage, avec une valeur de repli explicite. sanitize_hex_color() vérifie le format ; esc_attr() protège l’attribut HTML. Ce code pédagogique n’enregistre aucune nouvelle préférence.

Résultat observable

Le texte de démonstration utilise la couleur valide mémorisée pour le thème actif ou, à défaut, celle fournie comme repli.

Exercice de vérification pratique

Dans un thème de test, comparer le résultat avec une valeur de personnalisation valide et une valeur invalide. Observer qu’une valeur refusée ne doit pas être utilisée comme style.

Pièges, limites et sécurité

Une valeur stockée ne doit jamais être considérée comme sûre par principe. Les theme mods sont liés à l’identité du thème, et leurs usages diffèrent des styles globaux de l’éditeur de site.

Différences avec les notions voisines

get_theme_mod() lit un réglage du thème ; get_option() lit une option générale du site ; set_theme_mod() écrit un réglage du thème.

Diagnostic avancé et cas de maintenance

Cas avancé : un réglage de couleur fonctionne avec un thème mais disparaît après changement de thème. Les theme mods appartiennent au thème et ne constituent pas une configuration universelle du site. Préparer les valeurs de repli et documenter l’éventuelle migration lors d’une refonte.