# get_theme_mod et set_theme_mod : stocker les réglages sans base custom

> Vendre un thème à plusieurs clients impose de bien nommer et migrer ses réglages. Voici comment structurer get_theme_mod et set_theme_mod pour tenir sur la durée.

- Auteur : Clément Hadrot
- Publié le : 2021-02-22
- Mis à jour le : 2021-02-22
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/get-theme-mod-set-theme-mod-stocker-reglages/

## L’essentiel

- Préfixer chaque nom de mod évite les collisions entre thèmes
- Toujours fournir une valeur par défaut explicite en second argument
- Une routine de migration protège les mises à jour majeures

Un studio graphique m'a confié la maintenance d'un thème qu'il revend en marque blanche à une quinzaine de clients, chacun avec ses propres réglages de couleurs, de disposition d'en-tête et d'affichage d'articles. Le thème utilisait déjà l'API des theme mods, mais sans convention de nommage claire ni gestion des valeurs par défaut, ce qui provoquait des erreurs silencieuses à chaque mise à jour majeure : un réglage introduit dans une nouvelle version restait vide chez les clients existants, faute de valeur de repli.

Ce tutoriel détaille comment j'ai structuré le stockage des réglages avec `get_theme_mod()` et `set_theme_mod()` pour un thème destiné à plusieurs clients, sans recourir à une table personnalisée ni à une dépendance externe. L'API du Customizer côté interface (contrôles, sections, panneaux) n'est pas traitée ici : seul le stockage et sa fiabilité m'intéressent dans cet article.

## Ce que stocke réellement un theme mod

Les réglages enregistrés via `set_theme_mod()` vivent dans une entrée unique de la table `wp_options`, nommée `theme_mods_{stylesheet}`, où `{stylesheet}` correspond au dossier du thème actif. Concrètement, c'est un tableau PHP sérialisé contenant toutes les paires clé-valeur du thème. Changer de thème actif change automatiquement d'entrée : les réglages d'un thème n'écrasent jamais ceux d'un autre thème installé sur le même site, ce qui est rassurant pour un thème vendu en marque blanche coexistant parfois avec un thème de test.

```
$header_color = get_theme_mod( 'header_background_color', '#1a1a1a' );
set_theme_mod( 'header_background_color', '#0f3d2e' );
```

## La convention de nommage qui évite les collisions

Rien n'empêche deux thèmes différents de définir un mod nommé `header_color`, mais un client qui bascule un jour entre deux variantes du thème (une version restaurant, une version cabinet médical, partageant le même socle de code) peut se retrouver avec des noms de mods qui divergent d'une variante à l'autre si la discipline n'est pas tenue. Sur ce projet, j'ai adopté un préfixe court lié à la marque du studio, appliqué systématiquement.

- `stg_header_layout` plutôt que `header_layout`, pour éviter toute collision avec un futur plugin ou thème enfant.
- Un seul point d'enregistrement centralisé des noms de mods, dans `inc/customizer-defaults.php`, servant de source de vérité.
- Aucun mod stocké sans valeur par défaut explicite au moment de la lecture.

> L'essentiel à retenir : Préfixer chaque nom de mod évite les collisions entre thèmes ; Toujours fournir une valeur par défaut explicite en second argument ; Une routine de migration protège les mises à jour majeures

## Toujours fournir une valeur par défaut à la lecture

L'erreur la plus fréquente que j'ai corrigée consistait à appeler `get_theme_mod( 'stg_header_layout' )` sans second argument. Sans valeur par défaut, la fonction renvoie `false` si le mod n'a jamais été défini, ce qui oblige le reste du code à gérer un cas supplémentaire à chaque utilisation. En centralisant les valeurs par défaut dans un tableau unique, la maintenance devient bien plus prévisible.

```
function stg_theme_mod_defaults() {
    return array(
        'stg_header_layout'        => 'centered',
        'stg_header_background'    => '#ffffff',
        'stg_show_excerpt_on_home' => true,
    );
}

function stg_get_mod( $name ) {
    $defaults = stg_theme_mod_defaults();
    $default  = isset( $defaults[ $name ] ) ? $defaults[ $name ] : '';
    return get_theme_mod( $name, $default );
}
```

Chaque appel dans les templates passe désormais par `stg_get_mod()` plutôt que directement par `get_theme_mod()`, ce qui garantit qu'un oubli de valeur par défaut à un endroit du code ne produit jamais un résultat incohérent ailleurs.

## Migrer les mods entre versions majeures

Quand la version 3 du thème a renommé `stg_header_layout` en `stg_header_style` pour plus de clarté, il fallait éviter que les quinze clients existants perdent leur réglage du jour au lendemain. La solution retenue : une routine de migration exécutée une seule fois, déclenchée par comparaison de version stockée dans un mod dédié.

```
function stg_maybe_migrate_mods() {
    $version = get_theme_mod( 'stg_theme_version', '2.0' );

    if ( version_compare( $version, '3.0', '<' ) ) {
        $old_value = get_theme_mod( 'stg_header_layout' );
        if ( $old_value ) {
            set_theme_mod( 'stg_header_style', $old_value );
        }
        set_theme_mod( 'stg_theme_version', '3.0' );
    }
}
add_action( 'after_switch_theme', 'stg_maybe_migrate_mods' );
```

Ce type de migration reste minimal et ciblé : il ne recopie que les mods réellement renommés, et ne s'exécute qu'une fois par site grâce au verrou de version. Sur les quinze clients concernés, la mise à jour s'est faite sans aucun réglage perdu, ni intervention manuelle de leur part.

### Nettoyer les mods obsolètes

Un theme mod qui n'est plus lu nulle part dans le code continue pourtant d'exister dans `wp_options`, sans gêner le fonctionnement du site mais en alourdissant légèrement l'entrée sérialisée. Sur ce projet, j'ai profité de chaque migration majeure pour supprimer explicitement les mods devenus inutiles avec `remove_theme_mod()`, plutôt que de les laisser traîner indéfiniment.

## En résumé

L'API des theme mods reste largement suffisante pour un thème vendu à plusieurs clients, à condition d'imposer une discipline de nommage préfixé, de centraliser les valeurs par défaut et de prévoir une routine de migration à chaque renommage. Ces trois habitudes évitent la majorité des régressions silencieuses observées lors des montées de version d'un thème partagé entre de nombreux sites indépendants.