Skip to content

Commit a9c8ed6

Browse files
weaverryanweaverryan
committed
[#1829] Moving serializer framework docs around - added a new cookbook and linked to that from everywhere else
1 parent 18f4575 commit a9c8ed6

File tree

5 files changed

+119
-55
lines changed

5 files changed

+119
-55
lines changed

‎cookbook/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ The Cookbook
1212
form/index
1313
validation/index
1414
configuration/index
15+
serializer
1516
service_container/index
1617
bundles/index
1718
email/index

‎cookbook/map.rst.inc

+4
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,10 @@
122122
* :doc:`/cookbook/security/custom_authentication_provider`
123123
* :doc:`/cookbook/security/target_path`
124124

125+
* **Serializer**
126+
127+
* :doc:`/cookbook/serializer`
128+
125129
* :doc:`/cookbook/service_container/index`
126130

127131
* :doc:`/cookbook/service_container/event_listener`

‎cookbook/serializer.rst

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
.. index::
2+
single: Serializer
3+
4+
How to use the Serializer
5+
=========================
6+
7+
Serializing and deserializing to and from objects and different formats (e.g.
8+
JSON or XML) is a very complex topic. Symfony comes with a
9+
:doc:`Serializer Component</components/serializer>`, which gives you some
10+
tools that you can leverage for your solution.
11+
12+
In fact, before you start, get familiar with the serializer, normalizers
13+
and encoders by reading the :doc:`Serializer Component</components/serializer>`.
14+
You should also check out the `JMSSerializerBundle`_, which expands on the
15+
functionality offered by Symfony's core serializer.
16+
17+
Activating the Serializer
18+
-------------------------
19+
20+
.. versionadded:: 2.3
21+
The Serializer has always existed in Symfony, but prior to Symfony 2.3,
22+
you needed to build the ``serializer`` service yourself.
23+
24+
The ``serializer`` service is not available by default. To turn it on, activate
25+
it in your configuration:
26+
27+
.. configuration-block::
28+
29+
.. code-block:: yaml
30+
31+
# app/config/config.yml
32+
framework:
33+
# ...
34+
serializer:
35+
enabled: true
36+
37+
.. code-block:: xml
38+
39+
<!-- app/config/config.xml -->
40+
<framework:config ...>
41+
<!-- ... -->
42+
<framework:serializer enabled="true" />
43+
</framework:config>
44+
45+
.. code-block:: php
46+
47+
// app/config/config.php
48+
$container->loadFromExtension('framework', array(
49+
// ...
50+
'serializer' => array(
51+
'enabled' => true
52+
),
53+
));
54+
55+
Adding Normalizers and Encoders
56+
-------------------------------
57+
58+
Once enabled, the ``serializer`` service will be available in the container
59+
and will be loaded with two :ref:`encoders<component-serializer-encoders>`
60+
(:class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` and
61+
:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`)
62+
but no :ref:`normalizers<component-serializer-normalizers>`, meaning you'll
63+
need to load your own.
64+
65+
You can load normalizers and/or encoders by tagging them as
66+
:ref:`serializer.normalizer<reference-dic-tags-serializer-normalizer>` and
67+
:ref:`serializer.encoder<reference-dic-tags-serializer-encoder>`. It's also
68+
possible to set the priority of the tag in order to decide the matching order.
69+
70+
Here an example on how to load the load
71+
the :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`:
72+
73+
.. configuration-block::
74+
75+
.. code-block:: yaml
76+
77+
# app/config/config.yml
78+
services:
79+
get_set_method_normalizer:
80+
class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer
81+
tags:
82+
- { name: serializer.normalizer }
83+
84+
.. code-block:: xml
85+
86+
<!-- app/config/config.xml -->
87+
<services>
88+
<service id="get_set_method_normalizer" class="Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer">
89+
<tag name="serializer.normalizer" />
90+
</service>
91+
</services>
92+
93+
.. code-block:: php
94+
95+
// app/config/config.php
96+
use Symfony\Component\DependencyInjection\Definition;
97+
98+
$definition = new Definition(
99+
'Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer'
100+
));
101+
$definition->addTag('serializer.normalizer');
102+
$container->setDefinition('get_set_method_normalizer', $definition);
103+
104+
.. note::
105+
106+
The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`
107+
is broken by design. As soon as you have a circular object graph, an
108+
infinite loop is created when calling the getters. You're encouraged
109+
to add your own normalizers that fit your use-case.
110+
111+
.. _JMSSerializerBundle: http://jmsyst.com/bundles/JMSSerializerBundle

‎reference/configuration/framework.rst

+1-51
Original file line numberDiff line numberDiff line change
@@ -257,58 +257,8 @@ enabled
257257
**type**: ``boolean`` **default**: ``false``
258258

259259
Whether to enable the ``serializer`` service or not in the service container.
260-
If enabled, the ``serializer`` service will be available in the container
261-
and will be loaded with two :ref:`encoders<component-serializer-encoders>`
262-
(:class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` and
263-
:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`)
264-
but no :ref:`normalizers<component-serializer-normalizers>`, meaning you'll
265-
need to load your own.
266260

267-
You can load normalizers and/or encoders by tagging them as
268-
:ref:`serializer.normalizer<reference-dic-tags-serializer-normalizer>` and
269-
:ref:`serializer.encoder<reference-dic-tags-serializer-encoder>`. It's also
270-
possible to set the priority of the tag in order to decide the matching order.
271-
272-
Here an example on how to load the load
273-
the :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`:
274-
275-
.. configuration-block::
276-
277-
.. code-block:: yaml
278-
279-
# app/config/config.yml
280-
services:
281-
get_set_method_normalizer:
282-
class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer
283-
tags:
284-
- { name: serializer.normalizer }
285-
286-
.. code-block:: xml
287-
288-
<!-- app/config/config.xml -->
289-
<services>
290-
<service id="get_set_method_normalizer" class="Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer">
291-
<tag name="serializer.normalizer" />
292-
</service>
293-
</services>
294-
295-
.. code-block:: php
296-
297-
// app/config/config.php
298-
use Symfony\Component\DependencyInjection\Definition;
299-
300-
$definition = new Definition(
301-
'Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer'
302-
));
303-
$definition->addTag('serializer.normalizer');
304-
$container->setDefinition('get_set_method_normalizer', $definition);
305-
306-
.. note::
307-
308-
The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`
309-
is broken by design. As soon as you have a circular object graph, an
310-
infinite loop is created when calling the getters. You're encouraged
311-
to add your own normalizers that fit your use-case.
261+
For more details, see :doc:`/cookbook/serializer`.
312262

313263
templating
314264
~~~~~~~~~~

‎reference/dic_tags.rst

+2-4
Original file line numberDiff line numberDiff line change
@@ -574,8 +574,7 @@ serializer.encoder
574574
The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface`
575575
and :class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface`.
576576

577-
You have to :ref:`enable the serializer service<configuration-framework-serializer>`
578-
in order to use this tag.
577+
For more details, see :doc:`/cookbook/serializer`.
579578

580579
.. _reference-dic-tags-serializer-normalizer:
581580

@@ -587,8 +586,7 @@ serializer.normalizer
587586
The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface`
588587
and :class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface`.
589588

590-
You have to :ref:`enable the serializer service<configuration-framework-serializer>`
591-
in order to use this tag.
589+
For more details, see :doc:`/cookbook/serializer`.
592590

593591
swiftmailer.plugin
594592
------------------

0 commit comments

Comments
 (0)