Reorganize the Serializer documentation

Author: GuilhemN

components/index.rst

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

components/map.rst.inc

@@ -1,7 +1,7 @@
 * :doc:`/components/using_components`
 
 * :doc:`/components/browser_kit/index`
-  
+
   * :doc:`/components/browser_kit/introduction`
 
 * :doc:`/components/class_loader/index`
@@ -121,9 +121,11 @@
   * :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`
+  * :doc:`/components/serializer/normalizers`
 
 * **Stopwatch**
 

components/serializer/encoders.rst

@@ -0,0 +1,5 @@
+.. index::
+   single: Serializer, Encoders
+
+Encoders
+========

components/serializer/index.rst

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

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

@@ -47,11 +47,20 @@ which Encoders and Normalizer are going to be available::
     use Symfony\Component\Serializer\Encoder\JsonEncoder;
     use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
 
+    // Allows to serialize/deserialize in JSON and XML
     $encoders = array(new XmlEncoder(), new JsonEncoder());
+    // Allows to normalize objects thanks to their getters and setters
     $normalizers = array(new GetSetMethodNormalizer());
 
     $serializer = new Serializer($normalizers, $encoders);
 
+The following examples assume that you instantiate the serializer as above.
+
+.. note::
+
+    Read the dedicated sections to learn more about :doc:`/components/serializer/encoders`
+    and :doc:`/components/serializer/normalizers`.
+
 Serializing an Object
 ---------------------
 
@@ -65,7 +74,7 @@ exists in your project::
         private $age;
         private $name;
 
-        // Getters
+        // Getter
         public function getName()
         {
             return $this->name;
@@ -105,29 +114,6 @@ The first parameter of the :method:`Symfony\\Component\\Serializer\\Serializer::
 is the object to be serialized and the second is used to choose the proper encoder,
 in this case :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`.
 
-Ignoring Attributes when Serializing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 2.3
-    The :method:`GetSetMethodNormalizer::setIgnoredAttributes<Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setIgnoredAttributes>`
-    method was introduced in Symfony 2.3.
-
-As an option, there's a way to ignore attributes from the origin object when
-serializing. To remove those attributes use the
-:method:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setIgnoredAttributes`
-method on the normalizer definition::
-
-    use Symfony\Component\Serializer\Serializer;
-    use Symfony\Component\Serializer\Encoder\JsonEncoder;
-    use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
-
-    $normalizer = new GetSetMethodNormalizer();
-    $normalizer->setIgnoredAttributes(array('age'));
-    $encoder = new JsonEncoder();
-
-    $serializer = new Serializer(array($normalizer), array($encoder));
-    $serializer->serialize($person, 'json'); // Output: {"name":"foo"}
-
 Deserializing an Object
 -----------------------
 
@@ -141,6 +127,7 @@ of the ``Person`` class would be encoded in XML format::
     </person>
     EOF;
 
+    // Will return an instance of Acme\Person
     $person = $serializer->deserialize($data, 'Acme\Person', 'xml');
 
 In this case, :method:`Symfony\\Component\\Serializer\\Serializer::deserialize`
@@ -150,69 +137,11 @@ needs three parameters:
 #. The name of the class this information will be decoded to
 #. The encoder used to convert that information into an array
 
-Using Camelized Method Names for Underscored Attributes
--------------------------------------------------------
-
-.. versionadded:: 2.3
-    The :method:`GetSetMethodNormalizer::setCamelizedAttributes<Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setCamelizedAttributes>`
-    method was introduced in Symfony 2.3.
-
-Sometimes property names from the serialized content are underscored (e.g.
-``first_name``).  Normally, these attributes will use get/set methods like
-``getFirst_name``, when ``getFirstName`` method is what you really want. To
-change that behavior use the
-:method:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setCamelizedAttributes`
-method on the normalizer definition::
-
-    $encoder = new JsonEncoder();
-    $normalizer = new GetSetMethodNormalizer();
-    $normalizer->setCamelizedAttributes(array('first_name'));
-
-    $serializer = new Serializer(array($normalizer), array($encoder));
-
-    $json = <<<EOT
-    {
-        "name":       "foo",
-        "age":        "19",
-        "first_name": "bar"
-    }
-    EOT;
-
-    $person = $serializer->deserialize($json, 'Acme\Person', 'json');
-
-As a final result, the deserializer uses the ``first_name`` attribute as if
-it were ``firstName`` and uses the ``getFirstName`` and ``setFirstName`` methods.
-
-Using Callbacks to Serialize Properties with Object Instances
--------------------------------------------------------------
-
-When serializing, you can set a callback to format a specific object property::
-
-    use Acme\Person;
-    use Symfony\Component\Serializer\Encoder\JsonEncoder;
-    use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
-    use Symfony\Component\Serializer\Serializer;
-
-    $encoder = new JsonEncoder();
-    $normalizer = new GetSetMethodNormalizer();
-
-    $callback = function ($dateTime) {
-        return $dateTime instanceof \DateTime
-            ? $dateTime->format(\DateTime::ISO8601)
-            : '';
-    };
-
-    $normalizer->setCallbacks(array('createdAt' => $callback));
-
-    $serializer = new Serializer(array($normalizer), array($encoder));
-
-    $person = new Person();
-    $person->setName('cordoval');
-    $person->setAge(34);
-    $person->setCreatedAt(new \DateTime('now'));
+Go further
+----------
 
-    $serializer->serialize($person, 'json');
-    // Output: {"name":"cordoval", "age": 34, "createdAt": "2014-03-22T09:43:12-0500"}
+If this is not already done, you should take a look at :doc:`/components/serializer/encoders`
+and :doc:`/components/serializer/normalizers` to be able to use the entire abilities of this component.
 
 JMSSerializer
 -------------

components/serializer/normalizers.rst

@@ -0,0 +1,5 @@
+.. index::
+   single: Security, Normalizers
+
+Normalizers
+===========

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>`.
 You should also check out the `JMSSerializerBundle`_, which expands on the
 functionality offered by Symfony's core serializer.
 

redirection_map

@@ -24,6 +24,7 @@
 /components/routing /components/routing/introduction
 /cookbook/console/generating_urls /cookbook/console/sending_emails
 /components/yaml /components/yaml/introduction
+/components/serializer /components/serializer/introduction
 /components/templating /components/templating/introduction
 /cookbook/upgrading /cookbook/upgrade/index
 /cookbook/security/voters_data_permission /cookbook/security/voters