Helper Serializer

---

1Présentation

Ce helper sert à sérialiser et désérialiser des données aux formats PHP, JSON, INI, YAML, NEON et XML.

---

2Dépendances

Pour utiliser le format NEON, vous devez d'abord installer la dépendance nette/neon :

composer require nette/neon

---

3Désérialisation depuis une chaîne de caractères

3.1decode()

decode(string $stream, string|array $types=[self::PHP, self::JSON, self::INI, self::YAML, self::NEON, self::XML]) : mixed

Désérialise une chaîne de caractère dont le format est passé en second paramètre.

Le second paramètre peut prendre une des valeurs \Temma\Utils\Serializer::PHP, \Temma\Utils\Serializer::JSON, \Temma\Utils\Serializer::INI, \Temma\Utils\Serializer::YAML, \Temma\Utils\Serializer::NEON, \Temma\Utils\Serializer::XML.

Il peut aussi prendre une liste constituée de ces valeurs. Auquel cas les différents formats listés sont essayés, jusqu'à en trouver un qui fonctionne.

Exemple :

use \Temma\Utils\Serializer as TµSerializer;

// lit une chaîne JSON
$input = '{"aa": "bb"}';
$data = TµSerializer::decode($input, TµSerializer::JSON);

// lit une chaîne qui pourrait être en JSON ou en YAML
$data = TµSerializer::decode($input, [TµSerializer::JSON, TµSerializer::YAML]);

---

3.2decodePhp()

decodePhp(string $stream) : mixed

Désérialise une chaîne PHP.

---

3.3decodeJson()

decodeJson(string $stream) : mixed

Désérialise une chaîne JSON.

---

3.4decodeIni()

decodeIni(string $stream) : mixed

Désérialise une chaîne INI.

---

3.5decodeYaml()

decodeYaml(string $stream) : mixed

Désérialise une chaîne YAML.

---

3.6decodeNeon()

decodeNeon(string $stream) : mixed

Désérialise une chaîne NEON.

---

3.7decodeXml()

decodeXml(string $stream) : mixed

Désérialise une chaîne XML.

---

4Désérialisation depuis un fichier

4.1readFromPrefix()

readFromPrefix(string $prefixPath, array $types=[self::PHP, self::JSON, self::INI, self::YAML, self::NEON, self::XML]) : mixed

Cette méthode cherche un fichier dont le nom commence par la chaîne passée en premier paramètre, sans son extension. L'extension est ajoutée automatiquement pour trouver le fichier, en utilisant la liste passée en second paramètre. Le contenu du fichier est désérialisé en fonction du type trouvé.

Exemple :

use \Temma\Utils\Serializer as TµSerializer;

// lit un fichier 'toto.php' ou 'toto.json', 'toto.ini', 'toto.yaml', 'toto.neon', 'toto.xml'
$data = TµSerializer::readFromPrefix('toto');

// lit un fichier 'toto.json' ou 'toto.yaml'
$data = TµSerializer::readFromPrefix('toto', [TµSerializer::JSON, TµSerializer::YAML]);

---

4.2read()

read(string $path, ?string $type=null) : mixed

Désérialise le contenu du fichier dont le chemin est passé en premier paramètre. Le second paramètre peut recevoir le format de sérialisation ; s'il est laissé nul, le format est détecté à partir de l'extension du fichier.

Exemple :

// lit un fichier INI
$data = TµSerializer::read('toto.ini');

// lit un fichier XML
$data = TµSerializer::read('toto.txt', TµSerializer::XML);

---

4.3readPhp()

readPhp(string $path) : mixed

Désérialise un fichier PHP.

---

4.4readJson()

readJson(string $path) : mixed

Désérialise un fichier JSON.

---

4.5readIni()

readIni(string $path) : mixed

Désérialise un fichier INI.

---

4.6readYaml()

readYaml(string $path) : mixed

Désérialise un fichier YAML.

---

4.7readNeon()

readNeon(string $path) : mixed

Désérialise un fichier NEON.

---

4.8readXml()

readXml(string $path) : mixed

Désérialise un fichier XML.

---

5Sérialisation vers une chaîne de caractères

5.1encode()

encode(mixed $data, string $type) : string

Sérialise la donnée passée en premier paramètre, dans le format passé en second paramètre.

Le second paramètre peut prendre les valeurs \Temma\Utils\Serializer::PHP, \Temma\Utils\Serializer::JSON, \Temma\Utils\Serializer::INI, \Temma\Utils\Serializer::YAML, \Temma\Utils\Serializer::NEON, \Temma\Utils\Serializer::XML.

Exemple :

use \Temma\Utils\Serializer as TµSerializer;

$json = TµSerializer::encode($data, TµSerializer::JSON);

---

5.2encodePhp()

encodePhp(mixed $data) : string

Sérialise une donnée en code PHP.

---

5.3encodeJson()

encodePhp(mixed $data, bool $prettyPrint=true) : string

Sérialise une donnée au format JSON. Si le second paramètre est passé à false, le flux JSON est sur une seule ligne (sans retours chariots ni indentation).

---

5.4encodeIni()

encodeIni(mixed $data) : string

Sérialise une donnée au format INI.

---

5.5encodeYaml()

encodeYaml(mixed $data) : string

Sérialise une donnée au format YAML.

---

5.6encodeNeon()

encodeNeon(mixed $data) : string

Sérialise une donnée au format NEON.

---

5.7encodeXml()

encodeXml(mixed $data, bool $prettyPrint=true) : string

Sérialise une donnée au format XML. Si le second paramètre est passé à false, le flux XML est sans indentation.

---

6Sérialisation vers un fichier

6.1write()

write(string $path, mixed $data, ?string $type=null) : void

Sérialise la donnée passée en deuxième paramètre, et l'écrit dans le fichier dont le chemin est fourni en premier paramètre. Le format de sérialisation peut être donnée en troisième paramètre ; s'il est omis, il est deviné à partir de l'extension du fichier d'écriture (.php pour une sérialisation en code PHP, .json pour le format JSON, .ini pour le format INI, .yaml pour le format YAML, .neon pour le format NEON, .xml pour le format XML).

Le troisième paramètre peut prendre les valeurs \Temma\Utils\Serializer::PHP, \Temma\Utils\Serializer::JSON, \Temma\Utils\Serializer::INI, \Temma\Utils\Serializer::YAML, \Temma\Utils\Serializer::NEON, \Temma\Utils\Serializer::XML.

---

6.2writePhp()

writePhp(string $path, mixed $data) : void

Sérialise une donnée dans un fichier PHP.

---

6.3writeJson()

writeJson(string $path, mixed $data, bool $prettyPrint=true) : void

Sérialise une donnée dans un fichier JSON. Si le troisième paramètre est passé à false, le flux JSON est sur une seule ligne (sans retours chariots ni indentation).

---

6.4writeIni()

writeIni(string $path, mixed $data) : void

Sérialise une donnée dans un fichier INI.

---

6.5writeYaml()

writeYaml(string $path, mixed $data) : void

Sérialise une donnée dans un fichier YAML.

---

6.6writeNeon()

writeNeon(string $path, mixed $data) : void

Sérialise une donnée dans un fichier NEON.

---

6.7writeXml()

writeXml(string $path, mixed $data, bool $prettyPrint=true) : void

Sérialise une donnée dans un fichier XML. Si le troisième paramètre est passé à false, le flux XML est sans indentation.

---

7Formats de sérialisation

Cet objet gère les formats INI, YAML, NEON et XML standards. Certaines spécificités sont prises en charge pour les formats PHP et JSON.

---

7.1PHP

La désérialisation PHP est capable de lire un fichier PHP ou une chaîne de caractères PHP contenant une instruction return.

Exemple de fichier interprétable :

<?php

return [
	'abc' => 'def',
	'ghi' => 999,
];

Exemple de chaîne interprétable :

"return [12, 23, 34];"

---

7.2JSON

La désérialisation JSON est capable d'interpréter des fichiers ou des chaînes de caractères contenant un flux JSON. Ce flux JSON peut contenir des commentaires mono-ligne (// ...) ou multi-lignes (/* ... */).

Exemple de fichier interprétable :

/*
 * Fichier contenant la liste des utilisateurs
 */
[
    // administrateur
    {
        "name": "Alice",
        "role": "admin"
    },
    // gestionnaire
    {
        "name": "Bob",
        "role": "manager"
    }
]