Helper Serializer

---

1Presentation

This helper is used to serialize and deserialize data in PHP JSON, INI, YAML, NEON and XML formats.

---

2Dependencies

To use the NEON format, you must first install the nette/neon dependency:

composer require nette/neon

---

3Deserialization from a string

3.1decode()

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

Deserializes a character string whose format is passed as the second parameter.

The second parameter can take one of the values \Temma\Utils\Serializer::PHP, \Temma\Utils\Serializer::JSON, \Temma\Utils\Serializer::INI, \Temma\Utils\Serializer::YAML, \Temma\Utils\Serializer::NEON, \Temma\Utils\Serializer::XML.

It can also take a list of these values. In this case, the various formats listed are tried out, until a working one is found.

Example:

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

// reads a JSON string
$input = '{"aa": "bb"}';
$data = TµSerializer::decode($input, TµSerializer::JSON);

// reads a string that could be in JSON or YAML
$data = TµSerializer::decode($input, [TµSerializer::JSON, TµSerializer::YAML]);

---

3.2decodePhp()

decodePhp(string $stream) : mixed

Deserialize a PHP string.

---

3.3decodeJson()

decodeJson(string $stream) : mixed

Deserialize a JSON string.

---

3.4decodeIni()

decodeIni(string $stream) : mixed

Deserialize an INI string.

---

3.5decodeYaml()

decodeYaml(string $stream) : mixed

Deserialize a YAML string.

---

3.6decodeNeon()

decodeNeon(string $stream) : mixed

Deserialize a NEON string.

---

3.7decodeXml()

decodeXml(string $stream) : mixed

Deserialize an XML string.

---

4Deserialization from a file

4.1readFromPrefix()

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

This method searches for a file whose name begins with the string passed in the first parameter, without its extension. The extension is added automatically to find the file, using the list passed as the second parameter. The contents of the file are deserialized according to the type found.

Example:

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

// reads a file named 'foo.php' or 'foo.json', 'foo.ini', 'foo.yaml', 'foo.neon', 'foo.xml'
$data = TµSerializer::readFromPrefix('foo');

// reads a file named 'foo.json' or 'foo.yaml'
$data = TµSerializer::readFromPrefix('foo', [TµSerializer::JSON, TµSerializer::YAML]);

---

4.2read()

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

Unserializes the contents of the file whose path is passed as the first parameter. The second parameter can receive the serialization format; if left null, the format is detected from the file extension.

Exemple:

// reads an INI file
$data = TµSerializer::read('toto.ini');

// reads an XML file
$data = TµSerializer::read('toto.txt', TµSerializer::XML);

---

4.3readPhp()

readPhp(string $path) : mixed

Deserialize a PHP file.

---

4.4readJson()

readJson(string $path) : mixed

Deserialize a JSON file.

---

4.5readIni()

readIni(string $path) : mixed

Deserialize an INI file.

---

4.6readYaml()

readYaml(string $path) : mixed

Deserialize a YAML file.

---

4.7readNeon()

readNeon(string $path) : mixed

Deserialize a NEON file.

---

4.8readXml()

readXml(string $path) : mixed

Deserialize an XML file.

---

5Serialization to a string

5.1encode()

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

Serializes the data passed in the first parameter, in the format passed in the second parameter.

The second parameter can take the values \Temma\Utils\Serializer::PHP, \Temma\Utils\Serializer::JSON, \Temma\Utils\Serializer::INI, \Temma\Utils\Serializer::YAML, \Temma\Utils\Serializer::NEON, \Temma\Utils\Serializer::XML.

Example:

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

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

---

5.2encodePhp()

encodePhp(mixed $data) : string

Serialize data in PHP code.

---

5.3encodeJson()

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

Serializes data in JSON format. If the second parameter is set to false, the JSON stream is on a single line (without carriage returns or indentation).

---

5.4encodeIni()

encodeIni(mixed $data) : string

Serialize data in INI format.

---

5.5encodeYaml()

encodeYaml(mixed $data) : string

Serialize data in YAML format.

---

5.6encodeNeon()

encodeNeon(mixed $data) : string

Serialize data in NEON format.

---

5.7encodeXml()

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

Serializes data in XML format. If the second parameter is set to false, the XML stream is unindented.

---

6Serialization to a file

6.1write()

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

Serializes the data passed in the second parameter, and writes it to the file whose path is given in the first parameter. The serialization format can be given as the third parameter; if omitted, it is guessed from the extension of the written file (.php for serialization in PHP code, .json for JSON format, .ini for INI format, .yaml for YAML format, .neon for NEON format, .xml for XML format).

The third parameter can take the values \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

Serialize data in a PHP file.

---

6.3writeJson()

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

Serializes data in a JSON file. If the third parameter is set to false, the JSON stream is on a single line (without carriage returns or indentation).

---

6.4writeIni()

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

Serialize data in an INI file.

---

6.5writeYaml()

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

Serialize data in a YAML file.

---

6.6writeNeon()

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

Serialize data in a NEON file.

---

6.7writeXml()

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

Serializes data in an XML file. If the third parameter is set to false, the XML stream is unindented.

---

7Serialization formats

This object supports standard INI, YAML, NEON and XML formats. Some specific features are supported for PHP and JSON formats.

---

7.1PHP

PHP deserialization is able to read a PHP file or a PHP string containing a return statement.

Example of an interpretable file:

<?php

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

Example of an interpretable string:

"return [12, 23, 34];"

---

7.2JSON

JSON deserialization is capable of interpreting files or strings containing a JSON stream. This JSON stream can contain single-line comments (// ...) and multi-line comments (/* ... */).

Example of an interpretable file:

/*
 * User list list
 */
[
    // administrator
    {
        "name": "Alice",
        "role": "admin"
    },
    // manager
    {
        "name": "Bob",
        "role": "manager"
    }
]