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"
             abstract="true" />
             
Note that we have declared this definition abstract, we will later see
why. At the moment, do not worry too much about this. 

What is left to do is to publish our new handler to this bundle. So it gets
picked up, and wired with the correct serializer. In order to do this, this
bundle uses a configuration system similar to that of the SecurityBundle. Each
handler needs a corresponding factory::

    <?php
    
    namespace Acme\FooBundle\DependencyInjection\Factory;
    
    use JMS\SerializerBundle\DependencyInjection\SerializerFactoryInterface;
    
    class MyHandlerFactory implements SerializerFactoryInterface
    {
        public function getKey()
        {
            return 'acme_foo_my';
        }
        
        public function addConfiguration(ArrayNodeDefinition $builder)
        {
        
        }
        
        public function process(ContainerBuilder $container, array $config, $id)
        {
        
        }
    }
    
This factory is responsible for setting up the configuration for your handler
in the ``addConfiguration`` method, and then process that configuration in the
``process`` 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->addFactory(new FooFactory());
        }
    }