updated docs

Resources/doc/cookbook/custom_handlers.rst

@@ -1,104 +0,0 @@
-Custom De-/Serialization Handlers
-=================================
-
-Introduction
-------------
-This allows you to change the way of how a specifc type is being de-/serialized.
-
-Any handler must implement either the ``SerializationHandlerInterface``, or
-``DeserializationHandlerInterface``, or both. This bundle already comes with
-some handlers which you find in the Serializer/Handler folder, and which you
-can use as a starting point.
-
-Custom handlers are normal services, and thus can have dependencies on any
-other service available in the dependency injection container.
-
-Configuration
--------------
-After you have written your handler, you can write a service definition. Such
-as the following:
-
-.. code-block :: xml
-
-    <service id="acme_foo.serializer.my_handler"
-             class="Acme\FooBundle\Serializer\MyHandler"
-             public="false"
-             />
-             
-The Handler Factory
--------------------
-What is left to do is to publish our new handler to this bundle. So it gets
-picked up, and wired correctly. In order to do this, this bundle uses a 
-configuration system similar to that of the SecurityBundle. Each handler needs 
-a corresponding definition factory:
-
-.. code-block :: php
-
-    <?php
-    
-    namespace Acme\FooBundle\DependencyInjection\Factory;
-    
-    use JMS\SerializerBundle\DependencyInjection\HandlerFactoryInterface;
-    
-    class MyHandlerFactory implements HandlerFactoryInterface
-    {
-        public function getConfigKey()
-        {
-            return 'acme_foo_my';
-        }
-        
-        public function getType(array $config)
-        {
-            return self::TYPE_SERIALIZATION | self::TYPE_DESERIALIZATION;
-        }
-        
-        public function addConfiguration(ArrayNodeDefinition $builder)
-        {
-            $builder
-                ->children()
-                    ->scalarNode('foo')->end()
-                    ->scalarNode('bar')->end()
-                ->end()
-            ;
-        }
-        
-        public function getHandlerId(ContainerBuilder $container, array $config)
-        {
-            return 'acme_foo.serializer.my_handler';
-        }
-    }
-    
-This factory is responsible for setting up the configuration for your handler
-in the ``addConfiguration`` method, and then process that configuration in the
-``getHandlerId`` method. 
-
-The last thing left to do, is to add this factory to this bundle. This is
-done by adding a ``configureSerializerExtension`` to your bundle class:
-
-.. code-block :: php
-
-    <?php
-    
-    namespace Acme\FooBundle;
-    
-    use Acme\FooBundle\DependencyInjection\Factory\FooFactory;
-    use JMS\SerializerBundle\DependencyInjection\JMSSerializerExtension;
-    use Symfony\Component\HttpKernel\Bundle\Bundle;
-    
-    class AcmeFooBundle extends Bundle
-    {
-        public function configureSerializerExtension(JMSSerializerExtension $ext)
-        {
-            $ext->addHandlerFactory(new FooFactory());
-        }
-    }
-
-Enabling Your Handler
----------------------
-
-TODO: Add example config
-
-.. tip ::
-    
-    The order in which the handlers are listed in the "handlers" section defines
-    in which they are called while processing. 

Resources/doc/event_system.rst

@@ -0,0 +1,51 @@
+Event System
+============
+
+The serializer dispatches different events during the serialization, and 
+deserialization process which you can use to hook in and alter the default
+behavior.
+
+Register an Event Listener, or Subscriber
+-----------------------------------------
+A listener is a simple callable which receives an event object. You can
+use the tags ``jms_serializer.event_listener``, or ``jms_serializer.event_subscriber``
+in order to register it.
+
+The semantics are mainly the same as registering a regular Symfony2 event listener 
+except that you can to specify some additional attributes:
+
+    - *format*: The format that you want to listen to; defaulting to all formats.
+    - *type*: The type name that you want to listen to; defaulting to all types.
+    - *direction*: The direction (serialization, or deserialization); defaulting to both.
+
+Events
+------
+
+.. note ::
+
+    Events are not dispatched by Symfony2's event dispatcher as such
+    you cannot register listeners with the ``kernel.event_listener`` tag,
+    or the @DI\Observe annotation. Please see above.
+
+serializer.pre_serialize
+~~~~~~~~~~~~~~~~~~~~~~~~
+This is dispatched before a type is visited. You have access to the visitor,
+data, and type. Listeners may modify the type that is being used for 
+serialization.
+
+**Event Object**: JMS\SerializerBundle\Serializer\EventDispatcher\PreSerializeEvent 
+
+serializer.post_serialize
+~~~~~~~~~~~~~~~~~~~~~~~~~
+This is dispatched right before a type is left. You can for example use this
+to add additional data to an object that you normally do not save inside
+objects such as links.
+
+**Event Object**: JMS\SerializerBundle\Serializer\EventDispatcher\Event 
+
+serializer.post_deserialize
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This is dispatched after a type is processed. You can use it to normalize 
+submitted data if you require external services for example.
+
+**Event Object**: JMS\SerializerBundle\Serializer\EventDispatcher\Event

Resources/doc/handlers.rst

@@ -0,0 +1,70 @@
+Handlers
+========
+
+Introduction
+------------
+Handlers allow you to change the serialization, or deserialization process
+for a single type/format combination.
+
+Handlers are simple callback which receive three arguments: the visitor,
+the data, and the type. 
+
+Configuration
+-------------
+You can register any service as a handler by adding either the ``jms_serializer.handler``,
+or the ``jms_serializer.subscribing_handler``.
+
+Using ``jms_serializer.subscribing_handler``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using this tag, the configuration is contained in the handler itself which makes it
+easier to share with other users, and easier to set-up in general:
+
+.. code-block :: php
+
+    <?php
+    
+    use JMS\SerializerBundle\Serializer\Handler\SubscribingHandlerInterface;
+    use JMS\SerializerBundle\Serializer\GraphNavigator;
+    use JMS\SerializerBundle\Serializer\JsonSerializationVisitor;
+    
+    class MyHandler implements SubscribingHandlerInterface
+    {
+        public static function getSubscribingMethods()
+        {
+            return array(
+                'direction' => GraphNavigator::DIRECTION_SERIALIZATION,
+                'format' => 'json',
+                'type' => 'DateTime',
+                'serializeDateTimeToJson',
+            );
+        }
+        
+        public function serializeDateTimeToJson(JsonSerializationVisitor $visitor, \DateTime $date, array $type)
+        {
+            return $date->format($type['params'][0]);
+        }
+    }
+
+.. code-block :: xml
+
+    <service id="my_handler" class="MyHandler" public="false">
+        <tag name="jms_serializer.subscribing_handler" />
+    </service>
+
+Using ``jms_serializer.handler``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you have a handler like above, you can also wire it using the ``jms_serializer.handler`` tag:
+
+.. code-block :: xml
+
+    <service id="my_handler" class="MyHandler" public="false">
+        <tag name="jms_serializer.handler" type="DateTime" direction="serialization" format="json"
+                    method="serializeDateTimeToJson" />
+    </service>
+
+.. tip ::
+
+    The ``direction`` attribute is not required if you want to support both directions. Likewise can the
+    ``method`` attribute be omitted, then a default using the scheme ``serializeTypeToFormat``,
+    or ``deserializeTypeFromFormat`` will be used for serialization or deserialization
+    respectively.

Resources/doc/index.rst

@@ -26,16 +26,21 @@ Documentation
     installation
     configuration
     usage
+    event_system
+    handlers
     reference
     cookbook
 
 - :doc:`Installation <installation>`
 - :doc:`Configuration <configuration>`
 - :doc:`Usage <usage>`
+- :doc:`Events <event_system>`
+- :doc:`Handlers <handlers>`
+
 - Recipies
-    * :doc:`Custom Handlers </cookbook/custom_handlers>`
     * :doc:`/cookbook/exclusion_strategies`
     * :doc:`/cookbook/metadata_for_third_party`
+    
 - Reference
     * :doc:`Annotations </reference/annotations>`
     * :doc:`XML Reference </reference/xml_reference>`