Serializer Encoders

The JsonEncoder

The JsonEncoder encodes to and decodes from JSON strings, based on the PHP json_encode and json_decode functions.

It can be useful to modify how these functions operate in certain instances by providing options such as JSON_PRESERVE_ZERO_FRACTION. You can use the serialization context to pass in these options using the key json_encode_options or json_decode_options respectively:

1
2
3

$this->serializer->serialize($data, 'json', [
    'json_encode_options' => \JSON_PRESERVE_ZERO_FRACTION,
]);

All context options available for the JSON encoder are:

json_decode_associative (default: false)

If set to true returns the result as an array, returns a nested stdClass hierarchy otherwise.

json_decode_detailed_errors (default: false)

If set to true exceptions thrown on parsing of JSON are more specific. Requires seld/jsonlint package.

json_decode_options (default: 0)

Flags passed to json_decode function.

json_encode_options (default: \JSON_PRESERVE_ZERO_FRACTION)

Flags passed to json_encode function.

json_decode_recursion_depth (default: 512)

Sets maximum recursion depth.

The CsvEncoder

The CsvEncoder encodes to and decodes from CSV. Serveral context options are available to customize the behavior of the encoder:

csv_delimiter (default: ,)

Sets the field delimiter separating values (one character only).

csv_enclosure (default: ")

Sets the field enclosure (one character only).

csv_end_of_line (default: \n)

Sets the character(s) used to mark the end of each line in the CSV file.

csv_escape_char (default: empty string)

Sets the escape character (at most one character).

csv_key_separator (default: .)

Sets the separator for array's keys during its flattening

csv_headers (default: [], inferred from input data's keys)

Sets the order of the header and data columns. E.g. if you set it to ['a', 'b', 'c'] and serialize ['c' => 3, 'a' => 1, 'b' => 2], the order will be a,b,c instead of the input order (c,a,b).

csv_escape_formulas (default: false)

Escapes fields containing formulas by prepending them with a \t character.

as_collection (default: true)

Always returns results as a collection, even if only one line is decoded.

no_headers (default: false)

Setting to false will use first row as headers when denormalizing, true generates numeric headers.

output_utf8_bom (default: false)

Outputs special UTF-8 BOM along with encoded data.

The XmlEncoder

This encoder transforms PHP values into XML and vice versa.

For example, take an object that is normalized as following:

1

$normalizedArray = ['foo' => [1, 2], 'bar' => true];

The XmlEncoder will encode this object like:

1
2
3
4
5
6

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <foo>1</foo>
    <foo>2</foo>
    <bar>1</bar>
</response>

The special # key can be used to define the data of a node:

1
2
3
4
5
6
7
8
9
10

['foo' => ['@bar' => 'value', '#' => 'baz']];

/* is encoded as follows:
   <?xml version="1.0"?>
   <response>
       <foo bar="value">
          baz
       </foo>
   </response>
 */

Furthermore, keys beginning with @ will be considered attributes, and the key #comment can be used for encoding XML comments:

1
2
3
4
5
6
7
8
9
10
11
12

$encoder = new XmlEncoder();
$xml = $encoder->encode([
    'foo' => ['@bar' => 'value'],
    'qux' => ['#comment' => 'A comment'],
], 'xml');
/* will return:
   <?xml version="1.0"?>
   <response>
       <foo bar="value"/>
       <qux><!-- A comment --!><qux>
   </response>
 */

You can pass the context key as_collection in order to have the results always as a collection.

1
2
3
4
5
6
7
8
9
10
11
12

$encoder = new XmlEncoder();
$encoder->encode([
    '@attribute1' => 'foo',
    '@attribute2' => 'bar',
    '#' => ['foo' => ['@bar' => 'value', '#' => 'baz']]
], 'xml');

// will return:
// <?xml version="1.0"?>
// <response attribute1="foo" attribute2="bar">
// <foo bar="value">baz</foo>
// </response>

1

$xmlEncoder->encode($array, 'xml', [XmlEncoder::ENCODER_IGNORED_NODE_TYPES => [\XML_COMMENT_NODE]]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

use Symfony\Component\Serializer\Encoder\XmlEncoder;

$data = [
    'id' => 'IDHNQIItNyQ',
    'date' => '2019-10-24',
];

$xmlEncoder->encode($data, 'xml', ['xml_format_output' => true]);
// outputs:
// <?xml version="1.0"?>
// <response>
//   <id>IDHNQIItNyQ</id>
//   <date>2019-10-24</date>
// </response>

$xmlEncoder->encode($data, 'xml', [
    'xml_format_output' => true,
    'xml_root_node_name' => 'track',
    'encoder_ignored_node_types' => [
        \XML_PI_NODE, // removes XML declaration (the leading xml tag)
    ],
]);
// outputs:
// <track>
//   <id>IDHNQIItNyQ</id>
//   <date>2019-10-24</date>
// </track>

The YamlEncoder

This encoder requires the Yaml Component and transforms from and to Yaml.

Like other encoder, several context options are available:

yaml_inline (default: 0)

The level where you switch to inline YAML.

yaml_indent (default: 0)

The level of indentation (used internally).

yaml_flags (default: 0)

A bit field of Yaml::DUMP_*/Yaml::PARSE_* constants to customize the encoding/decoding YAML string.

Creating a Custom Encoder

Imagine you want to serialize and deserialize NEON. For that you'll have to create your own encoder:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// src/Serializer/YamlEncoder.php
namespace App\Serializer;

use Nette\Neon\Neon;
use Symfony\Component\Serializer\Encoder\DecoderInterface;
use Symfony\Component\Serializer\Encoder\EncoderInterface;

class NeonEncoder implements EncoderInterface, DecoderInterface
{
    public function encode($data, string $format, array $context = [])
    {
        return Neon::encode($data);
    }

    public function supportsEncoding(string $format)
    {
        return 'neon' === $format;
    }

    public function decode(string $data, string $format, array $context = [])
    {
        return Neon::decode($data);
    }

    public function supportsDecoding(string $format)
    {
        return 'neon' === $format;
    }
}

1
2
3
4
5
6

# config/services.yaml
services:
    # ...

    App\Serializer\NeonEncoder:
        tags: ['serializer.encoder']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <!-- ... -->

        <service id="App\Serializer\NeonEncoder">
            <tag name="serializer.encoder"/>
        </service>
    </services>
</container>

1
2
3
4
5
6
7
8
9
10
11
12

// config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use App\Serializer\NeonEncoder;

return function(ContainerConfigurator $container) {
    // ...

    $services->set(NeonEncoder::class)
        ->tag('serializer.encoder')
    ;
};