Skip to content

Commit 5f14ff0

Browse files
GuilhemNGuilhemN
committed
[Serializer] Document the encoders
1 parent 379616a commit 5f14ff0

File tree

11 files changed

+199
-15
lines changed

11 files changed

+199
-15
lines changed

‎components/index.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The Components
2828
property_access/index
2929
routing/index
3030
security/index
31-
serializer
31+
serializer/index
3232
stopwatch
3333
templating/index
3434
translation/index

‎components/map.rst.inc

+3-2
Original file line numberDiff line numberDiff line change
@@ -140,9 +140,10 @@
140140
* :doc:`/components/security/authorization`
141141
* :doc:`/components/security/secure_tools`
142142

143-
* **Serializer**
143+
* :doc:`/components/serializer/index`
144144

145-
* :doc:`/components/serializer`
145+
* :doc:`/components/serializer/introduction`
146+
* :doc:`/components/serializer/encoders`
146147

147148
* **Stopwatch**
148149

‎components/serializer/encoders.rst

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
.. index::
2+
single: Serializer, Encoders
3+
4+
Encoders
5+
========
6+
7+
Encoders basically turn **arrays** into **formats** and vice versa.
8+
They implement
9+
:class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface` for
10+
encoding (array to format) and
11+
:class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface` for
12+
decoding (format to array).
13+
14+
You can add new encoders to a Serializer instance by using its second constructor argument::
15+
16+
use Symfony\Component\Serializer\Serializer;
17+
use Symfony\Component\Serializer\Encoder\XmlEncoder;
18+
use Symfony\Component\Serializer\Encoder\JsonEncoder;
19+
20+
$encoders = array(new XmlEncoder(), new JsonEncoder());
21+
$serializer = new Serializer(array(), $encoders);
22+
23+
Built-in Encoders
24+
-----------------
25+
26+
Two encoders are used in the example above:
27+
28+
* :class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder` to encode/decode XML
29+
* :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` to encode/decode JSON
30+
31+
The ``XmlEncoder``
32+
~~~~~~~~~~~~~~~~~~
33+
34+
This encoder transforms arrays into XML and vice versa.
35+
36+
For example, take an object normalized as following::
37+
38+
array('foo' => array(1, 2), 'bar' => true);
39+
40+
The ``XmlEncoder`` will encode this object like that::
41+
42+
<?xml version="1.0"?>
43+
<response>
44+
<foo>1</foo>
45+
<foo>2</foo>
46+
<bar>1</bar>
47+
</response>
48+
49+
Be aware that this encoder will consider keys beginning with ``@`` as attributes::
50+
51+
$encoder = new XmlEncoder();
52+
$encoder->encode(array('foo' => array('@bar' => 'value')));
53+
// will return:
54+
// <?xml version="1.0"?>
55+
// <response>
56+
// <foo bar="value" />
57+
// </response>
58+
59+
The ``JsonEncoder``
60+
~~~~~~~~~~~~~~~~~~~
61+
62+
The ``JsonEncoder`` is much simpler and is based on the PHP
63+
:phpfunction:`json_encode` and :phpfunction:`json_decode` functions.

‎components/serializer/index.rst

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Serializer
2+
==========
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction
8+
encoders

‎components/serializer.rst renamed to ‎components/serializer/introduction.rst

+9-5
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Usage
4444

4545
Using the Serializer component is really simple. You just need to set up
4646
the :class:`Symfony\\Component\\Serializer\\Serializer` specifying
47-
which Encoders and Normalizer are going to be available::
47+
which encoders and normalizers are going to be available::
4848

4949
use Symfony\Component\Serializer\Serializer;
5050
use Symfony\Component\Serializer\Encoder\XmlEncoder;
@@ -57,10 +57,14 @@ which Encoders and Normalizer are going to be available::
5757
$serializer = new Serializer($normalizers, $encoders);
5858

5959
The preferred normalizer is the
60-
:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`, but other
61-
normalizers are available.
62-
To read more about them, refer to the `Normalizers`_ section of this page. All
63-
the examples shown below use the ``ObjectNormalizer``.
60+
:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`,
61+
but other normalizers are available. All the examples shown below use
62+
the ``ObjectNormalizer``.
63+
64+
.. seealso::
65+
66+
Read the dedicated sections to learn more about :doc:`/components/serializer/encoders`
67+
and `Normalizers`_.
6468

6569
Serializing an Object
6670
---------------------

‎cookbook/map.rst.inc

+3-2
Original file line numberDiff line numberDiff line change
@@ -187,9 +187,10 @@
187187
* :doc:`/cookbook/security/securing_services`
188188
* :doc:`/cookbook/security/access_control`
189189

190-
* **Serializer**
190+
* :doc:`/cookbook/serializer/index`
191191

192-
* :doc:`/cookbook/serializer`
192+
* :doc:`/cookbook/serializer/introduction`
193+
* :doc:`/cookbook/serializer/encoders`
193194

194195
* :doc:`/cookbook/service_container/index`
195196

‎cookbook/serializer/custom_encoders.rst

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
.. index::
2+
single: Serializer; Custom encoders
3+
4+
How to Create your Custom Encoder
5+
=================================
6+
7+
The :doc:`Serializer Component </components/serializer/index>` uses Normalizers
8+
to transform any data to an array that can be then converted in whatever
9+
data-structured language you want thanks to Encoders.
10+
11+
The Component provides several built-in encoders that are described
12+
:doc:`in their own section </components/serializer/encoders>` but you may want
13+
to use another language not supported.
14+
15+
Creating a new encoder
16+
----------------------
17+
18+
Imagine you want to serialize and deserialize Yaml. For that you'll have to
19+
create your own encoder that may use the
20+
:doc:`Yaml Component </components/yaml/index>`::
21+
22+
namespace AppBundle\Encoder;
23+
24+
use Symfony\Component\Serializer\Encoder\DecoderInterface;
25+
use Symfony\Component\Serializer\Encoder\EncoderInterface;
26+
use Symfony\Component\Yaml\Yaml;
27+
28+
class YamlEncoder implements EncoderInterface, DecoderInterface
29+
{
30+
public function encode($data, $format, array $context = array())
31+
{
32+
return Yaml::dump($data);
33+
}
34+
35+
public function supportsEncoding($format)
36+
{
37+
return 'yaml' === $format;
38+
}
39+
40+
public function decode($data, $format, array $context = array())
41+
{
42+
return Yaml::parse($data);
43+
}
44+
45+
public function supportsDecoding($format)
46+
{
47+
return 'yaml' === $format;
48+
}
49+
}
50+
51+
Registering it in your app
52+
--------------------------
53+
54+
If you use the Symfony Framework then you probably want to register this encoder
55+
as a service in your app. Then you only need to tag it as `serializer.encoder` and it will be
56+
injected in the Serializer.
57+
58+
.. configuration-block::
59+
60+
.. code-block:: yaml
61+
62+
# app/config/services.yml
63+
services:
64+
app.encoder.yaml:
65+
class: AppBundle\Encoder\YamlEncoder
66+
tags:
67+
- { name: serializer.encoder }
68+
69+
.. code-block:: xml
70+
71+
<!-- app/config/services.xml -->
72+
<?xml version="1.0" encoding="UTF-8" ?>
73+
<container xmlns="http://symfony.com/schema/dic/services"
74+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
75+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
76+
77+
<services>
78+
<service id="app.encoder.yaml" class="AppBundle\Encoder\YamlEncoder">
79+
<tag name="serializer.encoder" />
80+
</service>
81+
</services>
82+
</container>
83+
84+
.. code-block:: php
85+
86+
// app/config/services.php
87+
$container
88+
->register(
89+
'app.encoder.yaml',
90+
'AppBundle\Encoder\YamlEncoder'
91+
)
92+
->addTag('serializer.encoder')
93+
;
94+
95+
Now you'll be able to serialize and deserialize Yaml!
96+
97+
.. _tracker: https://github.com/symfony/symfony/issues

‎cookbook/serializer/index.rst

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Serializer
2+
==========
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction
8+
custom_encoders

‎cookbook/serializer.rst renamed to ‎cookbook/serializer/introduction.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
.. index::
2-
single: Serializer
2+
single: Serializer; Introduction
33

44
How to Use the Serializer
55
=========================
66

77
Serializing and deserializing to and from objects and different formats (e.g.
88
JSON or XML) is a very complex topic. Symfony comes with a
9-
:doc:`Serializer Component </components/serializer>`, which gives you some
9+
:doc:`Serializer Component </components/serializer/index>`, which gives you some
1010
tools that you can leverage for your solution.
1111

1212
In fact, before you start, get familiar with the serializer, normalizers
13-
and encoders by reading the :doc:`Serializer Component </components/serializer>`.
13+
and encoders by reading the :doc:`Serializer Component </components/serializer/index>`.
1414

1515
Activating the Serializer
1616
-------------------------

‎redirection_map

+2
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
/cookbook/email /cookbook/email/email
1111
/cookbook/gmail /cookbook/email/gmail
1212
/cookbook/console /components/console
13+
/cookbook/serializer /cookbook/serializer/introduction
1314
/cookbook/tools/autoloader /components/class_loader
1415
/cookbook/tools/finder /components/finder
1516
/cookbook/service_container/parentservices /components/dependency_injection/parentservices
@@ -26,6 +27,7 @@
2627
/components/yaml /components/yaml/introduction
2728
/components/templating /components/templating/introduction
2829
/components/filesystem /components/filesystem/introduction
30+
/components/serializer /components/serializer/introduction
2931
/cmf/reference/configuration/block /cmf/bundles/block/configuration
3032
/cmf/reference/configuration/content /cmf/bundles/content/configuration
3133
/cmf/reference/configuration/core /cmf/bundles/core/configuration

‎reference/dic_tags.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -946,7 +946,7 @@ serializer.encoder
946946
The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface`
947947
and :class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface`.
948948

949-
For more details, see :doc:`/cookbook/serializer`.
949+
For more details, see :doc:`/cookbook/serializer/introduction`.
950950

951951
.. _reference-dic-tags-serializer-normalizer:
952952

@@ -958,7 +958,7 @@ serializer.normalizer
958958
The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface`
959959
and :class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface`.
960960

961-
For more details, see :doc:`/cookbook/serializer`.
961+
For more details, see :doc:`/cookbook/serializer/introduction`.
962962

963963
swiftmailer.default.plugin
964964
--------------------------

0 commit comments

Comments
 (0)