[Serializer] Doc for groups support

Author: dunglas

components/serializer.rst

@@ -116,29 +116,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","sportsman":false}
-
 Deserializing an Object
 -----------------------
 
@@ -162,6 +139,145 @@ needs three parameters:
 2. The name of the class this information will be decoded to
 3. The encoder used to convert that information into an array
 
+Attributes Groups
+-----------------
+
+.. versionadded:: 2.7
+    The support of serialization and deserialization groups has been added
+    in Symfony 2.7.
+
+Sometimes, you want to serialize different set of attributes from your
+entities. Groups are a handy way to achieve this need.
+
+Lets start with a simple Plain Old PHP object.
+
+    namespace Acme;
+
+    class MyObj
+    {
+        public $foo;
+        public $bar;
+    }
+
+The definition of serialization can be specified using annotations, XML
+and YAML. The :class:Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory
+that will be used by the normalizer must be aware of the format to use.
+
+If you want to use annotations to define groups, initialize the :class:Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory
+like the following:
+
+    use Symfony\Component\Serializer\Mapping\Loader\AnnotationLoader;
+    use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
+
+    $classMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
+
+If you prefer XML:
+
+    use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
+    use Symfony\Component\Serializer\Mapping\Loader\XmlFileLoader;
+
+    $classMetadataFactory = new ClassMetadataFactory(new XmlFileLoader('/path/to/your/definition.xml'));
+
+And for YAML:
+
+    use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
+    use Symfony\Component\Serializer\Mapping\Loader\YamlFileLoader;
+
+    $classMetadataFactory = new ClassMetadataFactory(new YamlFileLoader('/path/to/your/definition.yml'));
+
+Then, create your groups definition:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        namespace Acme;
+
+        use Symfony\Component\Serializer\Annotation\Groups;
+
+        class MyObj
+        {
+            /**
+             * @Groups({"group1", "group2"})
+             */
+            public $foo;
+            /**
+             * @Groups({"group3"})
+             */
+            public $bar;
+        }
+
+    .. code-block:: yaml
+
+        Acme\MyObj:
+            attributes:
+                foo:
+                    groups: ['group1', 'group2']
+                bar:
+                    groups: ['group3']
+
+    .. code-block:: xml
+
+        <?xml version="1.0" ?>
+        <serializer xmlns="http://symfony.com/schema/dic/serializer"
+                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                            xsi:schemaLocation="http://symfony.com/schema/dic/serializer http://symfony.com/schema/dic/constraint-mapping/serializer-1.0.xsd">
+            <class name="Acme\MyObj">
+                <attribute name="foo">
+                    <group name="group1" />
+                    <group name="group2" />
+                </attribute>
+
+                <attribute name="bar">
+                    <group name="group3" />
+                </attribute>
+            </class>
+        </serializer>
+
+You are now able to serialize only attributes in the groups you want:
+
+    use Symfony\Component\Serializer\Serializer;
+    use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
+
+    $obj = new MyObj();
+    $obj->foo = 'foo';
+    $obj->bar = 'bar';
+
+    $normalizer = new PropertyNormalizer($classMetadataFactory);
+    $serializer = new Serializer(array($normalizer));
+
+    $data = $serializer->normalize($obj, null, array('groups' => array('group1')));
+    // $data = ['foo' => 'foo'];
+
+    $obj2 = $serializer->denormalize(array('foo' => 'foo', 'bar' => 'bar'), 'MyObj', null, array('groups' => array('group1', 'group3')));
+    // $obj2 = MyObj(foo: 'foo', bar: 'bar')
+
+Ignoring Attributes
+-------------------
+
+.. versionadded:: 2.3
+    The :method:`GetSetMethodNormalizer::setIgnoredAttributes<Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setIgnoredAttributes>`
+    method was introduced in Symfony 2.3.
+
+.. versionadded:: 2.7
+    Before Symfony 2.7, attributes was only ignored while serializing. Since Symfony
+    2.7, they are ignored when deserializing too.
+
+As an option, there's a way to ignore attributes from the origin object. 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","sportsman":false}
+
 Using Camelized Method Names for Underscored Attributes
 -------------------------------------------------------
 
@@ -333,14 +449,4 @@ having unique identifiers::
     echo $serializer->serialize($org, 'json');
     // {"name":"Les-Tilleuls.coop","members":[{"name":"K\u00e9vin", organization: "Les-Tilleuls.coop"]}
 
-JMSSerializer
--------------
-
-A popular third-party library, `JMS serializer`_, provides a more
-sophisticated albeit more complex solution. This library includes the
-ability to configure how your objects should be serialized/deserialized via
-annotations (as well as YAML, XML and PHP), integration with the Doctrine ORM,
-and handling of other complex cases.
-
-.. _`JMS serializer`: https://github.com/schmittjoh/serializer
 .. _Packagist: https://packagist.org/packages/symfony/serializer