feature #6976 [Finishing][Serializer] Document the encoders (Ener-Get…

…ick, weaverryan)

This PR was merged into the 2.7 branch.

Discussion
----------

[Finishing][Serializer] Document the encoders

Finishing #6684 - just opening the PR to review and run tests.

Commits
-------

10b2fa3 Minor language tweaks
f99663a removing cookbook entries
73172c6 updating links
33e5b76 Moving files into the new structure
2c66c83 Merge branch 'ENCODERS' of https://github.com/Ener-Getick/symfony-docs into Ener-Getick-ENCODERS
dbdbf68 [Serializer] Document the encoders

components/serializer.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 normalizer are going to be available::
 
     use Symfony\Component\Serializer\Serializer;
     use Symfony\Component\Serializer\Encoder\XmlEncoder;
@@ -57,10 +57,9 @@ 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``.
 
 Serializing an Object
 ---------------------

serializer.rst

@@ -226,8 +226,8 @@ A service leveraging `APCu`_ (and APC for PHP < 5.5) is built-in.
             ),
         ));
 
-Going Further with the Serializer Component
--------------------------------------------
+Going Further with the Serializer
+---------------------------------
 
 `ApiPlatform`_ provides an API system supporting `JSON-LD`_ and `Hydra Core Vocabulary`_
 hypermedia formats. It is built on top of the Symfony Framework and its Serializer
@@ -237,6 +237,12 @@ and a caching system.
 If you want to leverage the full power of the Symfony Serializer component,
 take a look at how this bundle works.
 
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    serializer/*
+
 .. _`APCu`: https://github.com/krakjoe/apcu
 .. _`ApiPlatform`: https://github.com/api-platform/core
 .. _`JSON-LD`: http://json-ld.org

serializer/custom_encoders.rst

@@ -0,0 +1,97 @@
+.. index::
+   single: Serializer; Custom encoders
+
+How to Create your Custom Encoder
+=================================
+
+The :doc:`Serializer Component </components/serializer>` uses Normalizers
+to transform any data to an array. Then, by leveraging *Encoders*, that data can
+be convereted into any data-structure (e.g. JSON).
+
+The Component provides several built-in encoders that are described
+:doc:`in their own section </serializer/encoders>` but you may want
+to use another structure that's not supported.
+
+Creating a new encoder
+----------------------
+
+Imagine you want to serialize and deserialize Yaml. For that you'll have to
+create your own encoder that uses the
+:doc:`Yaml Component </components/yaml>`::
+
+    namespace AppBundle\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 'yaml' === $format;
+        }
+
+        public function decode($data, $format, array $context = array())
+        {
+            return Yaml::parse($data);
+        }
+
+        public function supportsDecoding($format)
+        {
+            return 'yaml' === $format;
+        }
+    }
+
+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. Then, you only need to tag it with ``serializer.encoder``
+to inject your custom encoder into the Serializer.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            app.encoder.yaml:
+                class: AppBundle\Encoder\YamlEncoder
+                tags:
+                    - { name: serializer.encoder }
+
+    .. code-block:: xml
+
+        <!-- app/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 http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.encoder.yaml" class="AppBundle\Encoder\YamlEncoder">
+                    <tag name="serializer.encoder" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        $container
+            ->register(
+                'app.encoder.yaml',
+                'AppBundle\Encoder\YamlEncoder'
+            )
+            ->addTag('serializer.encoder')
+        ;
+
+Now you'll be able to serialize and deserialize Yaml!
+
+.. _tracker: https://github.com/symfony/symfony/issues

serializer/encoders.rst

@@ -0,0 +1,63 @@
+.. 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 transforms 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.