PHP JSON : retourner des données rapidement et sans erreur

Déboguer une API à l'arrache : pourquoi votre JSON retourne une erreur ?

Vous êtes-vous déjà retrouvé à trois heures du matin, les yeux rivés sur un écran Postman vide, en vous demandant : « Pourquoi mon script PHP renvoie du HTML au lieu du JSON ? » ? Si oui, vous n'êtes pas seul. Le sujet du retour de JSON depuis un script PHP cumule des dizaines de milliers de vues sur Stack Overflow, et ce n'est pas un hasard. Un développeur backend sur deux commet les mêmes erreurs : en-têtes oubliés, sortie parasite, Content-Type incorrect.

Dans cet article, nous ne nous contenterons pas de copier une réponse de forum. Nous allons voir comment retourner du JSON depuis PHP correctement, rapidement et sans surprises. Vous découvrirez pourquoi exit(json_encode($data)) peut vous trahir, comment gagner des millisecondes sur la sérialisation et que faire si votre JSON est « cassé ».

Prêt ? C'est parti.

Anatomie d'une réponse JSON correcte

Commençons par les bases. Voici comment ne pas faire :

<?php\n$data = ['status' => 'ok', 'message' => 'Bonjour !'];\necho json_encode($data);\n?>

Pourquoi est-ce mauvais ? D'abord, il n'y a pas d'en-tête Content-Type. Le navigateur ou le client peut interpréter la réponse comme du HTML ou du texte. Ensuite, si un espace, un echo ou un avertissement précède dans le code, le JSON sera corrompu.

Le modèle minimal correct ressemble à ceci :

<?php\nheader('Content-Type: application/json; charset=utf-8');\n$data = ['status' => 'ok', 'message' => 'Bonjour !'];\necho json_encode($data, JSON_UNESCAPED_UNICODE);\nexit;\n?>

Notez l'utilisation de JSON_UNESCAPED_UNICODE — il préserve les caractères accentués lisibles au lieu de les transformer en \\u0042\\u006f\\u006e\\u006a\\u006f\\u0075\\u0072. Et exit — une sécurité contre tout affichage accidentel après la réponse.

Les en-têtes : pas seulement le Content-Type

Pour optimiser les performances du JSON, ajoutez quelques en-têtes supplémentaires :

header('Content-Type: application/json; charset=utf-8');\nheader('X-Content-Type-Options: nosniff');\nheader('Cache-Control: no-cache, must-revalidate');

X-Content-Type-Options: nosniff empêche le navigateur de « deviner » le type de contenu — c'est une mesure de sécurité. Et Cache-Control est utile pour les données dynamiques, afin que le client ne mette pas en cache une réponse obsolète.

Gestion des erreurs : quand json_encode échoue

La fonction json_encode retourne false en cas d'échec. Et c'est là que les choses deviennent intéressantes. Si vous faites simplement echo json_encode($data) et que vous obtenez une chaîne vide en retour, le client sera perplexe.

Vérifiez toujours le résultat :

$json = json_encode($data, JSON_UNESCAPED_UNICODE);\nif ($json === false) {\n    http_response_code(500);\n    echo json_encode(['error' => 'Échec de l\'encodage JSON : ' . json_last_error_msg()]);\n    exit;\n}\necho $json;\nexit;

D'ailleurs, json_last_error_msg() retourne une chaîne explicite : « Malformed UTF-8 characters » ou « Inf and NaN cannot be JSON encoded ». Cela vous fera gagner des heures de débogage.

Données profondément imbriquées et récursion

Un autre problème : les références circulaires dans les objets. Si vous passez un objet avec des références mutuelles, json_encode générera une erreur. Solution : utilisez JSON_PARTIAL_OUTPUT_ON_ERROR ou convertissez d'abord l'objet en tableau.

$json = json_encode($complexObject, JSON_UNESCAPED_UNICODE | JSON_PARTIAL_OUTPUT_ON_ERROR);

Mais attention : la sortie partielle peut être incomplète. Il est préférable de corriger la structure des données.

Optimisation des performances JSON en PHP

Passons maintenant à la partie la plus intéressante : comment accélérer le retour de JSON depuis PHP.

1. Mise en cache du JSON sérialisé

Si les données changent rarement (référentiels, configurations, liste de villes), ne les sérialisez pas à chaque fois. Enregistrez le JSON prêt dans un fichier, Memcached