Skip to content

Commit 85845ab

Browse files
committed
[Serializer] Doc for groups support
1 parent 921f3cd commit 85845ab

File tree

1 file changed

+149
-30
lines changed

1 file changed

+149
-30
lines changed

components/serializer.rst

Lines changed: 149 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -116,29 +116,6 @@ The first parameter of the :method:`Symfony\\Component\\Serializer\\Serializer::
116116
is the object to be serialized and the second is used to choose the proper encoder,
117117
in this case :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`.
118118

119-
Ignoring Attributes when Serializing
120-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121-
122-
.. versionadded:: 2.3
123-
The :method:`GetSetMethodNormalizer::setIgnoredAttributes<Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setIgnoredAttributes>`
124-
method was introduced in Symfony 2.3.
125-
126-
As an option, there's a way to ignore attributes from the origin object when
127-
serializing. To remove those attributes use the
128-
:method:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setIgnoredAttributes`
129-
method on the normalizer definition::
130-
131-
use Symfony\Component\Serializer\Serializer;
132-
use Symfony\Component\Serializer\Encoder\JsonEncoder;
133-
use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
134-
135-
$normalizer = new GetSetMethodNormalizer();
136-
$normalizer->setIgnoredAttributes(array('age'));
137-
$encoder = new JsonEncoder();
138-
139-
$serializer = new Serializer(array($normalizer), array($encoder));
140-
$serializer->serialize($person, 'json'); // Output: {"name":"foo","sportsman":false}
141-
142119
Deserializing an Object
143120
-----------------------
144121

@@ -162,6 +139,152 @@ needs three parameters:
162139
2. The name of the class this information will be decoded to
163140
3. The encoder used to convert that information into an array
164141

142+
Attributes Groups
143+
-----------------
144+
145+
.. versionadded:: 2.7
146+
The support of serialization and deserialization groups was introduced
147+
in Symfony 2.7.
148+
149+
Sometimes, you want to serialize different sets of attributes from your
150+
entities. Groups are a handy way to achieve this need.
151+
152+
Assume you have the following plain-old-PHP object::
153+
154+
namespace Acme;
155+
156+
class MyObj
157+
{
158+
public $foo;
159+
public $bar;
160+
}
161+
162+
The definition of serialization can be specified using annotations, XML
163+
or YAML. The :class:`Symfony\\Component\\Serializer\\Mapping\\Factory\\ClassMetadataFactory`
164+
that will be used by the normalizer must be aware of the format to use.
165+
166+
Initialize the :class:`Symfony\\Component\\Serializer\\Mapping\\Factory\\ClassMetadataFactory`
167+
like the following::
168+
169+
use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory;
170+
// For annotations
171+
usr Doctrine\Common\Annotations\AnnotationReader;
172+
use Symfony\Component\Serializer\Mapping\Loader\AnnotationLoader;
173+
// For XML
174+
// use Symfony\Component\Serializer\Mapping\Loader\XmlFileLoader;
175+
// For YAML
176+
// use Symfony\Component\Serializer\Mapping\Loader\YamlFileLoader;
177+
178+
$classMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
179+
// For XML
180+
// $classMetadataFactory = new ClassMetadataFactory(new XmlFileLoader('/path/to/your/definition.xml'));
181+
// For YAML
182+
// $classMetadataFactory = new ClassMetadataFactory(new YamlFileLoader('/path/to/your/definition.yml'));
183+
184+
Then, create your groups definition:
185+
186+
.. configuration-block::
187+
188+
.. code-block:: php-annotations
189+
190+
namespace Acme;
191+
192+
use Symfony\Component\Serializer\Annotation\Groups;
193+
194+
class MyObj
195+
{
196+
/**
197+
* @Groups({"group1", "group2"})
198+
*/
199+
public $foo;
200+
201+
/**
202+
* @Groups({"group3"})
203+
*/
204+
public $bar;
205+
}
206+
207+
.. code-block:: yaml
208+
209+
Acme\MyObj:
210+
attributes:
211+
foo:
212+
groups: ['group1', 'group2']
213+
bar:
214+
groups: ['group3']
215+
216+
.. code-block:: xml
217+
218+
<?xml version="1.0" ?>
219+
<serializer xmlns="http://symfony.com/schema/dic/serializer-mapping"
220+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
221+
xsi:schemaLocation="http://symfony.com/schema/dic/serializer-mapping
222+
http://symfony.com/schema/dic/serializer-mapping/serializer-mapping-1.0.xsd"
223+
>
224+
<class name="Acme\MyObj">
225+
<attribute name="foo">
226+
<group>group1</group>
227+
<group>group2</group>
228+
</attribute>
229+
230+
<attribute name="bar">
231+
<group>group3</group>
232+
</attribute>
233+
</class>
234+
</serializer>
235+
236+
You are now able to serialize only attributes in the groups you want::
237+
238+
use Symfony\Component\Serializer\Serializer;
239+
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
240+
241+
$obj = new MyObj();
242+
$obj->foo = 'foo';
243+
$obj->bar = 'bar';
244+
245+
$normalizer = new ObjectNormalizer($classMetadataFactory);
246+
$serializer = new Serializer(array($normalizer));
247+
248+
$data = $serializer->normalize($obj, null, array('groups' => array('group1')));
249+
// $data = ['foo' => 'foo'];
250+
251+
$obj2 = $serializer->denormalize(
252+
array('foo' => 'foo', 'bar' => 'bar'),
253+
'MyObj',
254+
null,
255+
array('groups' => array('group1', 'group3'))
256+
);
257+
// $obj2 = MyObj(foo: 'foo', bar: 'bar')
258+
259+
.. _ignoring-attributes-when-serializing:
260+
261+
Ignoring Attributes
262+
-------------------
263+
264+
.. versionadded:: 2.3
265+
The :method:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setIgnoredAttributes`
266+
method was introduced in Symfony 2.3.
267+
268+
.. versionadded:: 2.7
269+
Prior to Symfony 2.7, attributes were only ignored while serializing. Since Symfony
270+
2.7, they are ignored when deserializing too.
271+
272+
As an option, there's a way to ignore attributes from the origin object. To remove
273+
those attributes use the
274+
:method:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer::setIgnoredAttributes`
275+
method on the normalizer definition::
276+
277+
use Symfony\Component\Serializer\Serializer;
278+
use Symfony\Component\Serializer\Encoder\JsonEncoder;
279+
use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
280+
281+
$normalizer = new GetSetMethodNormalizer();
282+
$normalizer->setIgnoredAttributes(array('age'));
283+
$encoder = new JsonEncoder();
284+
285+
$serializer = new Serializer(array($normalizer), array($encoder));
286+
$serializer->serialize($person, 'json'); // Output: {"name":"foo","sportsman":false}
287+
165288
Using Camelized Method Names for Underscored Attributes
166289
-------------------------------------------------------
167290

@@ -333,14 +456,10 @@ having unique identifiers::
333456
echo $serializer->serialize($org, 'json');
334457
// {"name":"Les-Tilleuls.coop","members":[{"name":"K\u00e9vin", organization: "Les-Tilleuls.coop"]}
335458

336-
JMSSerializer
337-
-------------
459+
.. seealso::
338460

339-
A popular third-party library, `JMS serializer`_, provides a more
340-
sophisticated albeit more complex solution. This library includes the
341-
ability to configure how your objects should be serialized/deserialized via
342-
annotations (as well as YAML, XML and PHP), integration with the Doctrine ORM,
343-
and handling of other complex cases.
461+
A popular alternative to the Symfony Serializer Component is the third-party
462+
library, `JMS serializer`_ (released under the Apache license, so incompatible with GPLv2 projects).
344463

345464
.. _`JMS serializer`: https://github.com/schmittjoh/serializer
346465
.. _Packagist: https://packagist.org/packages/symfony/serializer

0 commit comments

Comments
 (0)