Merge branch 'patch-1' of github.com:loalf/symfony-docs into loalf-patch-1

weaverryan · weaverryan · commit 18f457543594 · 2013-03-30T08:14:19.000-05:00
Also contains tweaks to #1829 Conflicts: reference/configuration/framework.rst
diff --git a/components/serializer.rst b/components/serializer.rst
@@ -11,6 +11,9 @@ The Serializer Component
 In order to do so, the Serializer Component follows the following
 simple schema.
 
+.. _component-serializer-encoders:
+.. _component-serializer-normalizers:
+
 .. image:: /images/components/serializer/serializer_workflow.png
 
 As you can see in the picture above, an array is used as a man in
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -34,6 +34,8 @@ Configuration
     * `gc_probability`_
     * `gc_maxlifetime`_
     * `save_path`_
+* `serializer`_
+    * `enabled`_
 * `templating`_
     * `assets_base_urls`_
     * `assets_version`_
@@ -244,6 +246,70 @@ save_path
 This determines the argument to be passed to the save handler. If you choose
 the default file handler, this is the path where the files are created.
 
+.. _configuration-framework-serializer:
+
+serializer
+~~~~~~~~~~
+
+enabled
+.......
+
+**type**: ``boolean`` **default**: ``false``
+
+Whether to enable the ``serializer`` service or not in the service container.
+If enabled, the ``serializer`` service will be available in the container
+and will be loaded with two :ref:`encoders<component-serializer-encoders>`
+(:class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` and
+:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`)
+but no :ref:`normalizers<component-serializer-normalizers>`, meaning you'll
+need to load your own.
+
+You can load normalizers and/or encoders by tagging them as
+:ref:`serializer.normalizer<reference-dic-tags-serializer-normalizer>` and
+:ref:`serializer.encoder<reference-dic-tags-serializer-encoder>`. It's also
+possible to set the priority of the tag in order to decide the matching order.
+
+Here an example on how to load the load 
+the :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`:
+
+.. configuration-block:: 
+
+    .. code-block:: yaml
+
+       # app/config/config.yml
+       services:
+          get_set_method_normalizer:
+             class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer
+             tags:
+                - { name: serializer.normalizer }
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <services>
+            <service id="get_set_method_normalizer" class="Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer">
+                <tag name="serializer.normalizer" />
+            </service>
+        </services>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        use Symfony\Component\DependencyInjection\Definition;
+
+        $definition = new Definition(
+            'Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer'
+        ));
+        $definition->addTag('serializer.normalizer');
+        $container->setDefinition('get_set_method_normalizer', $definition);
+
+.. note::
+
+    The :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`
+    is broken by design. As soon as you have a circular object graph, an
+    infinite loop is created when calling the getters. You're encouraged
+    to add your own normalizers that fit your use-case.
+
 templating
 ~~~~~~~~~~
 
@@ -462,6 +528,10 @@ Full Default Configuration
                 # DEPRECATED! Please use: cookie_httponly
                 httponly:             ~
 
+            # serializer configuration
+            serializer:
+               enabled: false
+
             # templating configuration
             templating:
                 assets_version:       ~
diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
@@ -42,6 +42,10 @@ the AsseticBundle has several tags that aren't listed here.
 +-----------------------------------+---------------------------------------------------------------------------+
 | `security.listener.factory`_      | Necessary when creating a custom authentication system                    |
 +-----------------------------------+---------------------------------------------------------------------------+
+| `serializer.encoder`_             | Register a new encoder in the ``serializer`` service                      |
++-----------------------------------+---------------------------------------------------------------------------+
+| `serializer.normalizer`_          | Register a new normalizer in the ``serializer`` service                   |
++-----------------------------------+---------------------------------------------------------------------------+
 | `swiftmailer.plugin`_             | Register a custom SwiftMailer Plugin                                      |
 +-----------------------------------+---------------------------------------------------------------------------+
 | `templating.helper`_              | Make your service available in PHP templates                              |
@@ -560,6 +564,32 @@ is used behind the scenes to determine if the user should have access. The
 
 For more information, read the cookbook article: :doc:`/cookbook/security/voters`.
 
+.. _reference-dic-tags-serializer-encoder:
+
+serializer.encoder
+------------------
+
+**Purpose**: Register a new encoder in the ``serializer`` service
+
+The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface`
+and :class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface`.
+
+You have to :ref:`enable the serializer service<configuration-framework-serializer>`
+in order to use this tag.
+
+.. _reference-dic-tags-serializer-normalizer:
+
+serializer.normalizer
+---------------------
+
+**Purpose**: Register a new normalizer in the Serializer service
+
+The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface`
+and :class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface`.
+
+You have to :ref:`enable the serializer service<configuration-framework-serializer>`
+in order to use this tag.
+
 swiftmailer.plugin
 ------------------
 
