# theme.json ne s’applique pas : cache, schéma invalide et ordre de priorité

> Un style modifié dans theme.json qui n'apparaît pas à l'écran ? Voici la méthode que nous suivons, du JSON invalide au cache de la feuille globale.

- Auteur : Clément Hadrot
- Publié le : 2023-11-02
- Mis à jour le : 2023-11-02
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/theme-json-ne-s-applique-pas-diagnostic/

## L’essentiel

- Un JSON invalide est silencieusement ignoré par WordPress
- Les styles enregistrés en base par l'éditeur passent devant le thème
- wp_get_global_stylesheet met en cache la feuille générée

« J'ai changé la couleur dans `theme.json`, mais rien ne bouge sur le site » : cette phrase revient régulièrement dans nos échanges de support avec des clients qui gèrent eux-mêmes des ajustements légers sur leur thème bloc. Le symptôme est toujours le même, mais les causes possibles sont multiples. Voici la méthode de diagnostic que nous suivons, dans l'ordre où nous vérifions chaque piste.

## Symptôme : un changement dans theme.json n'a aucun effet visible

Le développeur ou la développeuse modifie une valeur — une couleur de preset, une taille de police — enregistre le fichier, recharge la page, et rien ne change. Pas d'erreur PHP, pas de message dans la console : le site continue simplement d'afficher l'ancien style comme si le fichier n'avait jamais été modifié.

## Première piste : un JSON invalide

C'est la cause la plus fréquente, et la plus silencieuse. WordPress ne lève aucune erreur fatale si `theme.json` contient une virgule surnuméraire ou une accolade mal fermée : il ignore simplement le fichier et retombe sur les valeurs par défaut du cœur, sans le moindre message d'avertissement visible côté front.

```
{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "accent", "color": "#1d4ed8", }
      ]
    }
  }
}
```

Ici, la virgule après `"#1d4ed8"` rend le fichier invalide. Le réflexe à avoir : valider le fichier avec un outil dédié, ou plus simplement avec la commande `php -r "var_dump(json_decode(file_get_contents('theme.json')));"`, qui renvoie `NULL` en cas d'erreur de syntaxe.

## Deuxième piste : des styles utilisateur enregistrés en base

Si le JSON est valide, la piste suivante concerne les styles globaux enregistrés par l'éditeur de site lui-même. Depuis WordPress 5.9, chaque modification faite dans l'interface « Styles » de l'éditeur est stockée dans un post de type `wp_global_styles`, en base de données, et ces réglages sont prioritaires sur le fichier `theme.json` du thème.

> L'essentiel à retenir : Un JSON invalide est silencieusement ignoré par WordPress ; Les styles enregistrés en base par l'éditeur passent devant le thème ; wp_get_global_stylesheet met en cache la feuille générée

Concrètement, si quelqu'un a un jour changé la couleur d'accent depuis l'interface graphique, cette valeur reste enregistrée en base même après une modification du fichier source. Pour vérifier cette hypothèse, la méthode la plus rapide reste d'aller dans l'éditeur de site, section Styles, puis d'utiliser l'option de réinitialisation aux styles par défaut du thème — ce qui supprime les surcharges enregistrées en base.

## Troisième piste : le cache de la feuille de style globale

WordPress génère la feuille CSS finale à partir de `theme.json` et des styles utilisateur via la fonction interne `wp_get_global_stylesheet()`, et met le résultat en cache pour éviter de refaire ce calcul à chaque affichage de page. Sur un hébergement avec un cache d'objets persistant (Redis, Memcached), ce cache peut survivre à une simple modification de fichier si rien ne vient l'invalider.

```
wp_cache_delete( 'wp_global_styles', 'theme_json' );
```

Sur nos environnements, un simple vidage du cache d'objets depuis l'interface d'administration ou en ligne de commande WP-CLI (`wp cache flush`) suffit en général à forcer la régénération. Sur un hébergement mutualisé sans cache d'objets persistant, cette piste est rarement en cause : elle concerne surtout les infrastructures avec Redis ou un cache de type object-cache.php actif.

## Ordre de priorité à connaître

| Source | Priorité |
| --- | --- |
| Styles utilisateur (base de données, wp_global_styles) | La plus haute |
| theme.json du thème enfant, si présent | Intermédiaire |
| theme.json du thème parent | Intermédiaire, écrasé par l'enfant |
| Valeurs par défaut du cœur WordPress | La plus basse |

Cet ordre explique pourquoi une modification dans le `theme.json` du thème parent peut sembler sans effet : si le thème enfant redéclare la même clé, c'est cette dernière valeur qui l'emporte, quel que soit le contenu du parent.

> Avant de suspecter un bug de WordPress, commencez toujours par valider la syntaxe JSON. C'est la cause la plus bête, la plus fréquente, et celle qu'on oublie de vérifier en premier parce qu'on est sûr d'avoir bien écrit son fichier.

## Une checklist de diagnostic à suivre dans l'ordre

1. Valider la syntaxe JSON du fichier modifié.
2. Vérifier qu'aucun style utilisateur enregistré en base ne surcharge la clé concernée.
3. Identifier si un thème enfant redéclare la même clé que le parent.
4. Vider le cache d'objets si l'hébergement en utilise un persistant.

## En résumé

Un `theme.json` qui semble ignoré n'est presque jamais un bug de WordPress : c'est en général une erreur de syntaxe passée inaperçue, une surcharge enregistrée en base par l'éditeur, ou un cache d'objets qui n'a pas encore régénéré la feuille finale. Suivre ces trois pistes dans l'ordre permet de résoudre la quasi-totalité des cas remontés en support.