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"
}
]