# wp_json_encode plutôt que json_encode pour sérialiser un attribut de bloc

> Un caractère accentué mal encodé dans un attribut sérialisé, et voilà un bloc qui n'affiche plus qu'un point d'interrogation. Une fonction WordPress évite ce défaut discret.

- Auteur : WordPress Développement
- Publié le : 2021-03-13
- Mis à jour le : 2021-03-13
- Catégorie : Blocs Gutenberg
- URL : https://www.wpmoderne.fr/blocs/wp-json-encode-plutot-que-json-encode-attribut-bloc/

## L’essentiel

- wp_json_encode force l'encodage UTF-8 par défaut
- Gère les cas où mbstring n'est pas disponible sur le serveur
- Recommandé par les standards de codage WordPress

Trois caractères qui changent tout : `é`, `à`, `ç`. Un attribut de bloc contenant un texte accentué, sérialisé avec la fonction PHP native `json_encode()` sur un serveur mal configuré, peut ressortir avec des séquences d'échappement mal interprétées côté navigateur. Le bloc s'affiche alors avec des caractères remplacés par des points d'interrogation ou des carrés vides, un défaut particulièrement pénible à diagnostiquer parce qu'il ne se manifeste pas sur tous les environnements.

WordPress fournit sa propre fonction, `wp_json_encode()`, spécifiquement pensée pour éviter ce genre de problème et garantir un comportement homogène quel que soit le serveur d'hébergement.

## Ce que fait différemment wp_json_encode

`wp_json_encode()` est une enveloppe autour de `json_encode()`, mais elle ajoute deux garanties absentes de la fonction native : elle force l'encodage UTF-8 des données avant sérialisation, et elle vérifie la disponibilité de l'extension `mbstring`, en repliant sur une méthode alternative si elle est absente du serveur.

```
$donnees = [
    'titre' => 'Étude de cas : café équitable',
    'note'  => 4.5,
];

$json = wp_json_encode( $donnees );
// {"titre":"Étude de cas : café équitable","note":4.5}
```

Avec `json_encode()` seul, sur un serveur où l'encodage interne des chaînes PHP n'est pas garanti en UTF-8, le même appel peut produire une sortie corrompue ou déclencher un retour `false` silencieux, sans message d'erreur explicite dans les cas les plus problématiques.

## Application concrète : sérialiser un attribut de type objet

> L'essentiel à retenir : wp_json_encode force l'encodage UTF-8 par défaut ; Gère les cas où mbstring n'est pas disponible sur le serveur ; Recommandé par les standards de codage WordPress

Dans un bloc dynamique dont le rendu PHP doit transmettre une structure complexe à un composant JavaScript côté front (via `wp_localize_script()` ou une donnée injectée dans un attribut HTML), la sérialisation correcte devient critique :

```
function rendre_bloc_carte( $attributs ) {
    $config = [
        'centre' => $attributs['centre'] ?? [ 48.85, 2.35 ],
        'lieux'  => $attributs['lieux'] ?? [],
    ];

    return sprintf(
        '<div class="carte-interactive" data-config=\'%s\'></div>',
        esc_attr( wp_json_encode( $config ) )
    );
}
```

Notez la combinaison avec `esc_attr()` : `wp_json_encode()` garantit un JSON valide et bien encodé, mais ne protège pas contre l'injection de guillemets doubles dans un attribut HTML. Les deux fonctions se complètent, chacune avec un rôle distinct.

## Les options utiles à connaître

`wp_json_encode()` accepte les mêmes options que `json_encode()` natif en second argument, notamment `JSON_UNESCAPED_UNICODE` pour garder les caractères accentués lisibles dans la sortie plutôt que sous forme de séquences `\uXXXX`, utile en particulier pour déboguer une sortie stockée dans une base de données :

```
$json_lisible = wp_json_encode( $donnees, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT );
```

## Ce que disent les standards de codage WordPress

- Les standards de codage du projet recommandent explicitement `wp_json_encode()` à la place de `json_encode()` dans tout code destiné au cœur ou aux extensions officielles.
- Un outil d'analyse statique comme `PHP_CodeSniffer` configuré avec les règles WordPress signale l'usage direct de `json_encode()` comme un avertissement.
- La fonction retourne `false` en cas d'échec, comme son équivalent natif : il reste indispensable de vérifier ce retour avant de l'injecter tel quel dans une sortie HTML.

## Un cas où la différence est invisible en local, visible en production

Ce défaut a ceci de traître qu'il ne se manifeste pas nécessairement sur un environnement de développement local, où l'encodage par défaut du serveur PHP correspond souvent à celui attendu. Il apparaît en revanche sur certains hébergements mutualisés dont la configuration diffère, rendant le bug difficile à reproduire pour un développeur qui teste uniquement sur sa machine.

> Sur nos audits de code, `json_encode()` nu figure systématiquement parmi les premiers signalements, non pas parce qu'il casse toujours quelque chose, mais parce qu'il ne casse rien tant que l'environnement de test reste homogène avec la production.

## En résumé

Remplacer `json_encode()` par `wp_json_encode()` dans un bloc qui sérialise des attributs prend quelques secondes et élimine une classe entière de bugs liés à l'encodage, difficiles à reproduire sans accès direct au serveur concerné. Cette fonction fait partie des habitudes à intégrer dès le premier bloc écrit, avant même qu'un problème d'encodage ne se manifeste.