JMSSerializerBundle/Resources/doc/extending.rst

Extending The Serializer
========================

This document details the different extension points, and how you can utilize
them to change the default behavior of the serializer.

Custom De-/Serialization Handlers
---------------------------------
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.

After you have written your handler, you can write a service definition. Such
as the following::

    <service id="acme_foo.serializer.my_handler"
             class="Acme\FooBundle\Serializer\MyHandler"
             public="false"
             />
             
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::

    <?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::

    <?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());
        }
    }