Comment travailler avec JSON en PHP –

JSON est l’un des formats de sérialisation de données les plus couramment utilisés. Il a grandi depuis ses origines dans JavaScript (JSON signifie JavaScript Object Notation) pour devenir le format de choix pour de nombreuses API Web et systèmes de configuration.

PHP est livré avec un support JSON intégré. Historiquement, les fonctionnalités étaient fournies dans une extension distincte. Le lancement en 2020 de PHP 8.0 a converti JSON en une extension active en permanence qui ne peut pas être supprimée.

Lire les données JSON

Pour analyser les données JSON, utilisez le json_decode() fonction. Sa signature complète est la suivante:

json_decode(string $json, bool|null $associative=null, int $depth=512, int $flags=0) : mixed;

L’appel le plus simple consiste à transmettre une chaîne JSON sans autres arguments. Nous travaillerons avec {"foo": "bar"} qui décode en une instance du générique de PHP stdClass. Notre nouvel objet aura une propriété foo avec la valeur de bar.

Si vous préférez recevoir un tableau associatif, passez true à la $associative paramètre de json_decode(). L’exemple ci-dessus serait alors décodé en ["foo" => "bar"].

le $depth Le paramètre vous permet de contrôler le niveau d’imbrication maximal à analyser. Tu auras null si le JSON est imbriqué plus profondément que le niveau défini, aucune tentative ne sera faite pour analyser les données.

le $flags Le paramètre accepte un masque de bits d’indicateurs facultatifs qui modifient le comportement d’analyse. Ceux-ci sont décrits en détail dans le manuel PHP et vous permettent de définir comment des types de données spécifiques doivent être traités.

Gestion des erreurs d’analyse

Par défaut, json_decode() reviendra null lorsqu’il est passé une chaîne JSON non valide. Cela pose un problème car un null est une chaîne JSON valide. Vous n’avez aucun moyen de savoir si le null la valeur de retour est due au JSON contenant null, ou parce que le JSON était mal formé et n’a pas pu être analysé.

PHP 7.3 a finalement résolu ce problème de longue date en ajoutant le JSON_THROW_ON_ERROR drapeau. Passez cette constante au $flags paramètre de json_decode() pour que PHP lève une exception lorsqu’un JSON invalide est rencontré:

json_decode("['malformed json", true, 512, JSON_THROW_ON_ERROR);

Enabling this behaviour is generally desirable but it does make for a rather unwieldy invocation. You can use PHP 8’s named arguments to simplify things a bit, as you won’t need to pass explicit values for the optional parameters:

json_decode(json: "['malformed json", flags: JSON_THROW_ON_ERROR);

The two examples shown above are equivalent to each other. The only difference is the latter syntax requires PHP 8.

Serializing data to JSON

You can serialize PHP values into JSON strings using the json_encode() function. Its signature is as follows:

json_encode(mixed $value, int $flags=0, int $depth=512) : string|false;

PHP accepts any value as $value, except for resources. Data types are automatically handled to ensure they have an appropriate mapping in the generated JSON. PHP objects and associative arrays will become JSON objects containing all the enumerable property/key-value pairs of the input value. PHP scalar types map directly into JSON with no transformation.

Like its decoding counterpart, json_encode() accepts $flags and $depth parameters. Take care around the order though – in a quirk of the PHP standard library, the position of these two optional parameters is switched compared to json_decode().

Many more flags are supported when encoding data. Here’s some to be aware of:

• JSON_FORCE_OBJECT – Convert PHP numerical arrays to JSON objects instead of arrays. This handles the case where a variable contains an associative array which might be empty. When the array is empty ([]), un tableau JSON serait créé; quand ce n’est pas vide (["foo" => "bar"]), un objet serait émis à la place. L’activation de cet indicateur garantit qu’un objet est toujours utilisé dans le JSON codé.
• JSON_PRETTY_PRINT – La sortie JSON de PHP est normalement minifiée, ce qui est idéal lors de son envoi sur le réseau dans le cadre d’une requête HTTP. La définition de cet indicateur ajoutera de nouveaux caractères de ligne et une indentation automatique à la chaîne JSON, ce qui la rendra plus adaptée aux fichiers de configuration et à d’autres scénarios dans lesquels des humains liront la sortie.
• JSON_PRESERVE_ZERO_FRACTION – Force PHP à encoder des flottants tels que 0.0 exactement, au lieu de raser la fraction à écrire 0 dans le JSON (qui pourrait être incorrectement analysé comme un entier).
• JSON_NUMERIC_CHECK – Convertit automatiquement les chaînes numériques en nombres dans la sortie JSON, au lieu de les conserver sous forme de chaînes. Avec cette option activée, une valeur PHP "234.5" sera émis comme 234.5 dans le JSON.
• JSON_PARTIAL_OUTPUT_ON_ERROR – Essayez de continuer à écrire même après une erreur de codage. PHP essaiera de substituer des valeurs invalides afin de produire une sortie, même si elle n’est pas complète.

Vous pouvez obtenir la liste complète des indicateurs dans la documentation PHP. Les autres sont principalement des options spécifiques pour personnaliser l’encodage utilisé dans des scénarios particuliers.

Apporter JSON à la couche de domaine de votre application

Les backends Web complexes sont les plus susceptibles d’utiliser les fonctionnalités JSON de PHP dans le contexte de l’émission de réponses HTTP. Cela signifie probablement que vous encoderez des instances de classes de couche de domaine, telles que BlogPost.

Appel json_encode() avec une instance d’une classe donne une chaîne JSON contenant un seul objet. PHP énumérera les Publique propriétés de la classe et ajoutez-les en tant que paires clé / valeur dans l’objet codé JSON.

class BlogPost {
    protected int $Id = 1;
    public string $Title = "Example";
}
 
// produces '{"Title": "Example"}'
$json = json_encode(new BlogPost());

PHP ne peut pas accéder automatiquement aux propriétés protégées ou privées. Cette implémentation par défaut est donc insuffisante pour toutes les classes sauf la plus simple. Au lieu de cela, vos classes peuvent implémenter le JsonSerializable interface. Cela vous permet de définir comment les instances seront transformées en JSON.

JsonSerializable définit une seule méthode, jsonSerialize(), que PHP appellera chaque fois qu’une instance doit être sérialisée en JSON:

class BlogPost implements JsonSerializable {
    protected int $Id = 1;
    public string $Title = "Example";
 
    public function jsonSerialize() {
        return [
            "Id" => $this -> Id,
            "Title" => $this -> Title
        ];
    }
}
 
// produces '{"Id": 1, "Title": "Example"}'
$json = json_encode(new BlogPost());

Exécution JsonSerializable vous permet de prendre le contrôle du processus de sérialisation. Vos instances peuvent choisir les éléments à exposer, qui peuvent inclure des propriétés protégées, des valeurs calculées dynamiquement et des données renvoyées par des appels de méthode.

Vous n’avez même pas besoin de renvoyer un tableau. le jsonSerializable la signature de méthode spécifie un mixed return type, afin que vous puissiez fournir n’importe quelle valeur que PHP peut sérialiser en JSON. Vous pouvez renvoyer un autre objet pour que PHP le sérialise de manière récursive.