set_theme_mod()

Définition : set_theme_mod() enregistre ou modifie une valeur de personnalisation pour le thème WordPress actif. Elle est destinée aux réglages de présentation et doit être appelée depuis un traitement correctement autorisé.

Terminologie

Nom technique : set_theme_mod()

Appellations : Nom principal utilisé

À quoi cela sert, concrètement

Elle permet de conserver une préférence graphique spécifique au thème, par exemple une couleur choisie dans une interface de configuration, sans modifier manuellement functions.php.

Fonctionnement détaillé

WordPress écrit la valeur dans la collection des modifications du thème actif. La fonction retourne le résultat de l’opération et ne construit pas à elle seule de formulaire ni de contrôle d’accès.

Quand l’utiliser : contexte et choix techniques

L’utiliser uniquement après validation d’une demande légitime dans une interface d’administration ou un processus de personnalisation autorisé. Pour les thèmes de blocs, considérer également les styles globaux.

Situation professionnelle réaliste

Un administrateur enregistre une couleur d’accent autorisée via un formulaire interne du thème ; une future page relit cette valeur avec get_theme_mod().

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
// Extrait de handler administratif, action validée par formulaire.
add_action( 'admin_post_atoolpha_couleur_demo', function () {
    if ( ! current_user_can( 'edit_theme_options' ) ) {
        wp_die( 'Accès refusé.' );
    }
    check_admin_referer( 'atoolpha_couleur_demo' );
    $raw = isset( $_POST['couleur'] ) && is_string( $_POST['couleur'] )
        ? sanitize_text_field( wp_unslash( $_POST['couleur'] ) ) : '';
    $color = sanitize_hex_color( $raw );
    if ( ! $color ) { wp_die( 'Couleur invalide.' ); }
    set_theme_mod( 'atoolpha_accent', $color );
    wp_safe_redirect( admin_url( 'themes.php' ) );
    exit;
} );

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

Le handler vérifie d’abord la capacité edit_theme_options et un nonce de formulaire dont l’action est connue. Il lit une chaîne, valide le format de couleur, enregistre la valeur puis redirige vers une URL interne fixe.

Résultat observable

Une couleur valide est enregistrée pour le thème actif. Les demandes non autorisées ou les données invalides sont interrompues avant toute modification.

Exercice de vérification pratique

Dans une copie de développement, créer un formulaire POST vers admin-post.php avec action=atoolpha_couleur_demo, un champ couleur et un nonce correspondant. Tester le refus sans nonce ou avec couleur invalide.

Pièges, limites et sécurité

Ne jamais déclencher une écriture à chaque affichage public. Le nonce ne remplace pas la vérification des droits ; prévoir également le comportement de la valeur lors d’un changement de thème.

Différences avec les notions voisines

set_theme_mod() écrit ; get_theme_mod() lit. Ces réglages ne sont pas identiques aux options générales ni aux données de theme.json.

Diagnostic avancé et cas de maintenance

Cas avancé : un formulaire modifie la préférence graphique sans contrôle de droit. Le correctif consiste à vérifier une capacité adaptée, un nonce valide et la valeur soumise avant l’écriture, puis à rediriger vers une destination sûre. Tester expressément les refus, pas seulement le scénario réussi.