mirror of
https://github.com/symfony/symfony-docs.git
synced 2026-03-24 00:32:14 +01:00
f9c60f491a
* 6.4: Fix “construtor” typos across docs (constructor) Fix typo in encoders.rst (Serveral → Several)
379 lines
13 KiB
ReStructuredText
379 lines
13 KiB
ReStructuredText
Serializer Encoders
|
|
===================
|
|
|
|
The Serializer component provides several built-in encoders:
|
|
|
|
:class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`
|
|
This class encodes and decodes data in `JSON`_.
|
|
|
|
:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`
|
|
This class encodes and decodes data in `XML`_.
|
|
|
|
:class:`Symfony\\Component\\Serializer\\Encoder\\YamlEncoder`
|
|
This encoder encodes and decodes data in `YAML`_. This encoder requires the
|
|
:doc:`Yaml Component </components/yaml>`.
|
|
|
|
:class:`Symfony\\Component\\Serializer\\Encoder\\CsvEncoder`
|
|
This encoder encodes and decodes data in `CSV`_.
|
|
|
|
.. note::
|
|
|
|
You can also create your own encoder to use another structure. Read more at
|
|
:ref:`Creating a Custom Encoder <serializer-custom-encoder>` below.
|
|
|
|
All these encoders are enabled by default when using the Serializer component
|
|
in a Symfony application.
|
|
|
|
The ``JsonEncoder``
|
|
-------------------
|
|
|
|
The ``JsonEncoder`` encodes to and decodes from JSON strings, based on the PHP
|
|
:phpfunction:`json_encode` and :phpfunction:`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::
|
|
|
|
$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 :phpfunction:`json_decode` function.
|
|
``json_encode_options`` (default: ``\JSON_PRESERVE_ZERO_FRACTION``)
|
|
Flags passed to :phpfunction:`json_encode` function.
|
|
``json_decode_recursion_depth`` (default: ``512``)
|
|
Sets maximum recursion depth.
|
|
|
|
The ``CsvEncoder``
|
|
------------------
|
|
|
|
The ``CsvEncoder`` encodes to and decodes from CSV. Several :ref:`context options <serializer-context>`
|
|
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)
|
|
|
|
.. deprecated:: 7.2
|
|
|
|
The ``csv_escape_char`` option was deprecated in Symfony 7.2.
|
|
|
|
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::
|
|
|
|
$normalizedArray = ['foo' => [1, 2], 'bar' => true];
|
|
|
|
The ``XmlEncoder`` will encode this object like:
|
|
|
|
.. code-block:: xml
|
|
|
|
<?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::
|
|
|
|
['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::
|
|
|
|
$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.
|
|
|
|
.. note::
|
|
|
|
You may need to add some attributes on the root node::
|
|
|
|
$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>
|
|
|
|
.. tip::
|
|
|
|
XML comments are ignored by default when decoding contents, but this
|
|
behavior can be changed with the optional context key ``XmlEncoder::DECODER_IGNORED_NODE_TYPES``.
|
|
|
|
Data with ``#comment`` keys are encoded to XML comments by default. This can be
|
|
changed by adding the ``\XML_COMMENT_NODE`` option to the ``XmlEncoder::ENCODER_IGNORED_NODE_TYPES``
|
|
key of the ``$defaultContext`` of the ``XmlEncoder`` constructor or
|
|
directly to the ``$context`` argument of the ``encode()`` method::
|
|
|
|
$xmlEncoder->encode($array, 'xml', [XmlEncoder::ENCODER_IGNORED_NODE_TYPES => [\XML_COMMENT_NODE]]);
|
|
|
|
The ``XmlEncoder`` Context Options
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
These are the options available on the :ref:`serializer context <serializer-context>`:
|
|
|
|
``xml_format_output`` (default: ``false``)
|
|
If set to true, formats the generated XML with line breaks and indentation.
|
|
``xml_version`` (default: ``1.0``)
|
|
Sets the XML version attribute.
|
|
``xml_encoding`` (default: ``utf-8``)
|
|
Sets the XML encoding attribute.
|
|
``xml_standalone`` (default: ``true``)
|
|
Adds standalone attribute in the generated XML.
|
|
``xml_type_cast_attributes`` (default: ``true``)
|
|
This provides the ability to forget the attribute type casting.
|
|
``xml_root_node_name`` (default: ``response``)
|
|
Sets the root node name.
|
|
``as_collection`` (default: ``false``)
|
|
Always returns results as a collection, even if only one line is decoded.
|
|
``decoder_ignored_node_types`` (default: ``[\XML_PI_NODE, \XML_COMMENT_NODE]``)
|
|
Array of node types (`DOM XML_* constants`_) to be ignored while decoding.
|
|
``encoder_ignored_node_types`` (default: ``[]``)
|
|
Array of node types (`DOM XML_* constants`_) to be ignored while encoding.
|
|
``load_options`` (default: ``\LIBXML_NONET | \LIBXML_NOBLANKS``)
|
|
XML loading `options with libxml`_.
|
|
``save_options`` (default: ``0``)
|
|
XML saving `options with libxml`_.
|
|
``remove_empty_tags`` (default: ``false``)
|
|
If set to ``true``, removes all empty tags in the generated XML.
|
|
``cdata_wrapping`` (default: ``true``)
|
|
If set to ``false``, will not wrap any value containing one of the
|
|
following characters ( ``<``, ``>``, ``&``) in `a CDATA section`_ like
|
|
following: ``<![CDATA[...]]>``.
|
|
``cdata_wrapping_pattern`` (default: ``/[<>&]/``)
|
|
A regular expression pattern to determine if a value should be wrapped
|
|
in a CDATA section.
|
|
``ignore_empty_attributes`` (default: ``false``)
|
|
If set to true, ignores all attributes with empty values in the generated XML
|
|
|
|
.. versionadded:: 7.1
|
|
|
|
The ``cdata_wrapping_pattern`` option was introduced in Symfony 7.1.
|
|
|
|
.. versionadded:: 7.3
|
|
|
|
The ``ignore_empty_attributes`` option was introduced in Symfony 7.3.
|
|
|
|
Example with a custom ``context``::
|
|
|
|
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 :doc:`Yaml Component </components/yaml>` and
|
|
transforms from and to Yaml.
|
|
|
|
Like other encoder, several :ref:`context options <serializer-context>` 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.
|
|
|
|
.. _serializer-custom-encoder:
|
|
|
|
Creating a Custom Encoder
|
|
-------------------------
|
|
|
|
Imagine you want to serialize and deserialize `NEON`_. For that you'll have to
|
|
create your own encoder::
|
|
|
|
// src/Serializer/NeonEncoder.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;
|
|
}
|
|
}
|
|
|
|
.. tip::
|
|
|
|
If you need access to ``$context`` in your ``supportsDecoding`` or
|
|
``supportsEncoding`` method, make sure to implement
|
|
``Symfony\Component\Serializer\Encoder\ContextAwareDecoderInterface``
|
|
or ``Symfony\Component\Serializer\Encoder\ContextAwareEncoderInterface`` accordingly.
|
|
|
|
Registering it in Your App
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you use the Symfony Framework, then you probably want to register this encoder
|
|
as a service in your app. If you're using the
|
|
:ref:`default services.yaml configuration <service-container-services-load-example>`,
|
|
that's done automatically!
|
|
|
|
If you're not using :ref:`autoconfigure <services-autoconfigure>`, make sure
|
|
to register your class as a service and tag it with
|
|
:ref:`serializer.encoder <reference-dic-tags-serializer-encoder>`:
|
|
|
|
.. configuration-block::
|
|
|
|
.. code-block:: yaml
|
|
|
|
# config/services.yaml
|
|
services:
|
|
# ...
|
|
|
|
App\Serializer\NeonEncoder:
|
|
tags: ['serializer.encoder']
|
|
|
|
.. code-block:: xml
|
|
|
|
<!-- 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>
|
|
|
|
.. code-block:: php
|
|
|
|
// config/services.php
|
|
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
|
|
|
|
use App\Serializer\NeonEncoder;
|
|
|
|
return function(ContainerConfigurator $container) {
|
|
// ...
|
|
|
|
$services->set(NeonEncoder::class)
|
|
->tag('serializer.encoder')
|
|
;
|
|
};
|
|
|
|
Now you'll be able to serialize and deserialize NEON!
|
|
|
|
.. _JSON: https://www.json.org/json-en.html
|
|
.. _XML: https://www.w3.org/XML/
|
|
.. _YAML: https://yaml.org/
|
|
.. _CSV: https://tools.ietf.org/html/rfc4180
|
|
.. _seld/jsonlint: https://github.com/Seldaek/jsonlint
|
|
.. _`UTF-8 BOM`: https://en.wikipedia.org/wiki/Byte_order_mark
|
|
.. _`DOM XML_* constants`: https://www.php.net/manual/en/dom.constants.php
|
|
.. _`options with libxml`: https://www.php.net/manual/en/libxml.constants.php
|
|
.. _`a CDATA section`: https://en.wikipedia.org/wiki/CDATA
|
|
.. _NEON: https://ne-on.org/
|