Helper Serializer

---

1Apresentação

Este helper é usado para serializar e desserializar dados nos formatos JSON, INI, YAML, NEON e XML, além do PHP.

---

2Dependências

Para usar o formato NEON, você deve primeiro instalar a dependência nette/neon:

composer require nette/neon

---

3Desserialização a partir de uma string

3.1decode()

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

Desserializa uma string de caracteres cujo formato é passado como segundo parâmetro.

O segundo parâmetro pode receber um dos valores \Temma\Utils\Serializer::PHP, \Temma\Utils\Serializer::JSON, \Temma\Utils\Serializer::INI, \Temma\Utils\Serializer::YAML, \Temma\Utils\Serializer::NEON, \Temma\Utils\Serializer::XML.

Ele também pode receber uma lista desses valores. Nesse caso, os diversos formatos listados são testados, até que um funcione.

Exemplo:

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

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

// lê uma string que pode estar em JSON ou YAML
$data = TµSerializer::decode($input, [TµSerializer::JSON, TµSerializer::YAML]);

---

3.2decodePhp()

decodePhp(string $stream) : mixed

Desserializa uma string PHP.

---

3.3decodeJson()

decodeJson(string $stream) : mixed

Desserializa uma string JSON.

---

3.4decodeIni()

decodeIni(string $stream) : mixed

Desserializa uma string INI.

---

3.5decodeYaml()

decodeYaml(string $stream) : mixed

Desserializa uma string YAML.

---

3.6decodeNeon()

decodeNeon(string $stream) : mixed

Desserializa uma string NEON.

---

3.7decodeXml()

decodeXml(string $stream) : mixed

Desserializa uma string XML.

---

4Desserialização a partir de um arquivo

4.1readFromPrefix()

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

Este método procura um arquivo cujo nome comece com a string passada no primeiro parâmetro, sem sua extensão. A extensão é adicionada automaticamente para encontrar o arquivo, usando a lista passada como segundo parâmetro. O conteúdo do arquivo é desserializado de acordo com o tipo encontrado.

Exemplo:

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

// lê um arquivo chamado 'foo.php' ou 'foo.json', 'foo.ini', 'foo.yaml', 'foo.neon', 'foo.xml'
$data = TµSerializer::readFromPrefix('foo');

// lê um arquivo chamado 'foo.json' ou 'foo.yaml'
$data = TµSerializer::readFromPrefix('foo', [TµSerializer::JSON, TµSerializer::YAML]);

---

4.2read()

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

Desserializa o conteúdo do arquivo cujo caminho é passado como primeiro parâmetro. O segundo parâmetro pode receber o formato de serialização; se deixado nulo, o formato é detectado a partir da extensão do arquivo.

Exemplo:

// lê um arquivo INI
$data = TµSerializer::read('toto.ini');

// lê um arquivo XML
$data = TµSerializer::read('toto.txt', TµSerializer::XML);

---

4.3readPhp()

readPhp(string $path) : mixed

Desserializa um arquivo PHP.

---

4.4readJson()

readJson(string $path) : mixed

Desserializa um arquivo JSON.

---

4.5readIni()

readIni(string $path) : mixed

Desserializa um arquivo INI.

---

4.6readYaml()

readYaml(string $path) : mixed

Desserializa um arquivo YAML.

---

4.7readNeon()

readNeon(string $path) : mixed

Desserializa um arquivo NEON.

---

4.8readXml()

readXml(string $path) : mixed

Desserializa um arquivo XML.

---

5Serialização para uma string

5.1encode()

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

Serializa os dados passados no primeiro parâmetro, no formato passado no segundo parâmetro.

O segundo parâmetro pode receber os valores \Temma\Utils\Serializer::PHP, \Temma\Utils\Serializer::JSON, \Temma\Utils\Serializer::INI, \Temma\Utils\Serializer::YAML, \Temma\Utils\Serializer::NEON, \Temma\Utils\Serializer::XML.

Exemplo:

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

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

---

5.2encodePhp()

encodePhp(mixed $data) : string

Serializa dados em código PHP.

---

5.3encodeJson()

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

Serializa dados no formato JSON. Se o segundo parâmetro for definido como false, o fluxo JSON fica em uma única linha (sem quebras de linha ou indentação).

---

5.4encodeIni()

encodeIni(mixed $data) : string

Serializa dados no formato INI.

---

5.5encodeYaml()

encodeYaml(mixed $data) : string

Serializa dados no formato YAML.

---

5.6encodeNeon()

encodeNeon(mixed $data) : string

Serializa dados no formato NEON.

---

5.7encodeXml()

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

Serializa dados no formato XML. Se o segundo parâmetro for definido como false, o fluxo XML fica sem indentação.

---

6Serialização para um arquivo

6.1write()

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

Serializa os dados passados no segundo parâmetro, e os grava no arquivo cujo caminho é fornecido no primeiro parâmetro. O formato de serialização pode ser fornecido como terceiro parâmetro; se omitido, ele é deduzido a partir da extensão do arquivo gravado (.php para serialização em código PHP, .json para o formato JSON, .ini para o formato INI, .yaml para o formato YAML, .neon para o formato NEON, .xml para o formato XML).

O terceiro parâmetro pode receber os valores \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

Serializa dados em um arquivo PHP.

---

6.3writeJson()

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

Serializa dados em um arquivo JSON. Se o terceiro parâmetro for definido como false, o fluxo JSON fica em uma única linha (sem quebras de linha ou indentação).

---

6.4writeIni()

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

Serializa dados em um arquivo INI.

---

6.5writeYaml()

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

Serializa dados em um arquivo YAML.

---

6.6writeNeon()

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

Serializa dados em um arquivo NEON.

---

6.7writeXml()

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

Serializa dados em um arquivo XML. Se o terceiro parâmetro for definido como false, o fluxo XML fica sem indentação.

---

7Formatos de serialização

Este objeto suporta os formatos padrão INI, YAML, NEON e XML. Alguns recursos específicos são suportados para os formatos PHP e JSON.

---

7.1PHP

A desserialização PHP é capaz de ler um arquivo PHP ou uma string PHP contendo uma instrução return.

Exemplo de um arquivo interpretável:

<?php

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

Exemplo de uma string interpretável:

"return [12, 23, 34];"

---

7.2JSON

A desserialização JSON é capaz de interpretar arquivos ou strings contendo um fluxo JSON. Esse fluxo JSON pode conter comentários de linha única (// ...) e comentários de várias linhas (/* ... */).

Exemplo de um arquivo interpretável:

/*
 * Lista de usuários
 */
[
    // administrador
    {
        "name": "Alice",
        "role": "admin"
    },
    // gerente
    {
        "name": "Bob",
        "role": "manager"
    }
]