[Serializer] Document the encoders

Author: GuilhemN

components/index.rst

@@ -28,7 +28,7 @@ The Components
     property_access/index
     routing/index
     security/index
-    serializer
+    serializer/index
     stopwatch
     templating/index
     translation/index

components/map.rst.inc

@@ -140,9 +140,10 @@
   * :doc:`/components/security/authorization`
   * :doc:`/components/security/secure_tools`
 
-* **Serializer**
+* :doc:`/components/serializer/index`
 
-  * :doc:`/components/serializer`
+  * :doc:`/components/serializer/introduction`
+  * :doc:`/components/serializer/encoders`
 
 * **Stopwatch**
 

components/serializer/encoders.rst

@@ -0,0 +1,106 @@
+.. index::
+   single: Serializer, Encoders
+
+Encoders
+========
+
+Encoders basically turn **arrays** into **formats** and vice versa.
+They implement
+:class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface` for
+encoding (array to format) and
+:class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface` for
+decoding (format to array).
+
+You can add new encoders to a Serializer instance by using its second constructor argument::
+
+    use Symfony\Component\Serializer\Serializer;
+    use Symfony\Component\Serializer\Encoder\XmlEncoder;
+    use Symfony\Component\Serializer\Encoder\JsonEncoder;
+
+    $encoders = array(new XmlEncoder(), new JsonEncoder());
+    $serializer = new Serializer(array(), $encoders);
+
+Built-in encoders
+-----------------
+
+Two encoders are used in the example above:
+
+* :class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder` to encode/decode XML
+* :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` to encode/decode JSON
+
+The ``XmlEncoder``
+~~~~~~~~~~~~~~~~~~
+
+This encoder transform arrays into XML and vice versa.
+
+For example, take an object normalized as following::
+
+    array('foo' => array(1, 2), 'bar' => true);
+
+The ``XmlEncoder`` will encode this object like that::
+
+    <?xml version="1.0"?>
+    <response>
+        <foo>1</foo>
+        <foo>2</foo>
+        <bar>1</bar>
+    </response>
+
+Be aware that this encoder will consider keys beginning with ``@`` as attributes::
+
+    $encoder = new XmlEncoder();
+    $encoder->encode(array('foo' => array('@bar' => 'value')));
+    // will return:
+    // <?xml version="1.0"?>
+    // <response>
+    //     <foo bar="value" />
+    // </response>
+
+The ``JsonEncoder``
+~~~~~~~~~~~~~~~~~~~
+
+The ``JsonEncoder`` is much simpler and is based on the PHP :phpfunction:`json_encode` and :phpfunction:`json_decode` functions.
+
+Custom Encoders
+---------------
+
+If you need to support another format than XML and JSON, you can create your own encoder.
+You might want to serialize and deserialize Yaml. For that, you can use
+:doc:`/components/yaml/index`::
+
+    namespace App\Encoder;
+
+    use Symfony\Component\Serializer\Encoder\DecoderInterface;
+    use Symfony\Component\Serializer\Encoder\EncoderInterface;
+    use Symfony\Component\Yaml\Yaml;
+
+    class YamlEncoder implements EncoderInterface, DecoderInterface
+    {
+        public function encode($data, $format, array $context = array())
+        {
+            return Yaml::dump($data);
+        }
+
+        public function supportsEncoding($format)
+        {
+            return 'json' === $format;
+        }
+
+        public function decode($data, $format, array $context = array())
+        {
+            return Yaml::parse($data);
+        }
+
+        public function supportsDecoding($format)
+        {
+            return 'json' === $format;
+        }
+    }
+
+Then just pass it to your serializer::
+
+    use Symfony\Component\Serializer\Serializer;
+
+    $serializer = new Serializer(array(), array(new App\Encoder\YamlEncoder()));
+
+Now you'll be able to serialize and deserialize Yaml.

components/serializer/index.rst

@@ -0,0 +1,8 @@
+Serializer
+==========
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
+    encoders

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

@@ -44,7 +44,7 @@ Usage
 
 Using the Serializer component is really simple. You just need to set up
 the :class:`Symfony\\Component\\Serializer\\Serializer` specifying
-which Encoders and Normalizer are going to be available::
+which encoders and normalizers are going to be available::
 
     use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Encoder\XmlEncoder;
@@ -57,10 +57,14 @@ which Encoders and Normalizer are going to be available::
     $serializer = new Serializer($normalizers, $encoders);
 
 The preferred normalizer is the
-:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`, but other
-normalizers are available.
-To read more about them, refer to the `Normalizers`_ section of this page. All
-the examples shown below use the ``ObjectNormalizer``.
+:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`,
+but other normalizers are available. All the examples shown below use
+the ``ObjectNormalizer``.
+
+.. seealso::
+
+    Read the dedicated sections to learn more about :doc:`/components/serializer/encoders`
+    and `Normalizers`_.
 
 Serializing an Object
 ---------------------

cookbook/serializer.rst

@@ -6,11 +6,11 @@ How to Use the Serializer
 
 Serializing and deserializing to and from objects and different formats (e.g.
 JSON or XML) is a very complex topic. Symfony comes with a
-:doc:`Serializer Component </components/serializer>`, which gives you some
+:doc:`Serializer Component </components/serializer/index>`, which gives you some
 tools that you can leverage for your solution.
 
 In fact, before you start, get familiar with the serializer, normalizers
-and encoders by reading the :doc:`Serializer Component </components/serializer>`.
+and encoders by reading the :doc:`Serializer Component </components/serializer/index>`.
 
 Activating the Serializer
 -------------------------

redirection_map

@@ -26,6 +26,7 @@
 /components/yaml /components/yaml/introduction
 /components/templating /components/templating/introduction
 /components/filesystem /components/filesystem/introduction
+/components/serializer /components/serializer/introduction
 /cmf/reference/configuration/block /cmf/bundles/block/configuration
 /cmf/reference/configuration/content /cmf/bundles/content/configuration
 /cmf/reference/configuration/core /cmf/bundles/core/configuration