diff --git a/components/serializer.rst b/components/serializer.rst index eca1925cb0a..319ff81c483 100644 --- a/components/serializer.rst +++ b/components/serializer.rst @@ -145,6 +145,8 @@ needs three parameters: #. The name of the class this information will be decoded to #. The encoder used to convert that information into an array +.. _component-serializer-attributes-groups: + Attributes Groups ----------------- diff --git a/cookbook/serializer.rst b/cookbook/serializer.rst index 1f578cd3738..28c63e05b87 100644 --- a/cookbook/serializer.rst +++ b/cookbook/serializer.rst @@ -11,8 +11,6 @@ tools that you can leverage for your solution. In fact, before you start, get familiar with the serializer, normalizers and encoders by reading the :doc:`Serializer Component`. -You should also check out the `JMSSerializerBundle`_, which expands on the -functionality offered by Symfony's core serializer. Activating the Serializer ------------------------- @@ -48,23 +46,48 @@ it in your configuration: $container->loadFromExtension('framework', array( // ... 'serializer' => array( - 'enabled' => true + 'enabled' => true, ), )); +Using the Serializer Service +---------------------------- + +Once enabled, the ``serializer`` service can be injected in any service where +you need it or it can be used in a controller like the following:: + + // src/AppBundle/Controller/DefaultController.php + namespace AppBundle\Controller; + + use Symfony\Bundle\FrameworkBundle\Controller\Controller; + + class DefaultController extends Controller + { + public function indexAction() + { + $serializer = $this->get('serializer'); + + // ... + } + } + Adding Normalizers and Encoders ------------------------------- +.. versionadded:: 2.7 + The :class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer` + is enabled by default in Symfony 2.7. In prior versions, you need to load + your own normalizer. + Once enabled, the ``serializer`` service will be available in the container and will be loaded with two :ref:`encoders` (:class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` and -:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`) -but no :ref:`normalizers`, meaning you'll -need to load your own. +:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder`) and the +:ref:`ObjectNormalizer normalizer `. You can load normalizers and/or encoders by tagging them as -:ref:`serializer.normalizer` and -:ref:`serializer.encoder`. It's also +:ref:`serializer.normalizer ` and +:ref:`serializer.encoder `. It's also possible to set the priority of the tag in order to decide the matching order. Here is an example on how to load the @@ -101,4 +124,95 @@ Here is an example on how to load the $definition->addTag('serializer.normalizer'); $container->setDefinition('get_set_method_normalizer', $definition); -.. _JMSSerializerBundle: http://jmsyst.com/bundles/JMSSerializerBundle +Using Serialization Groups Annotations +-------------------------------------- + +.. versionadded:: 2.7 + Support for serialization groups was introduced in Symfony 2.7. + +Enable :ref:`serialization groups annotation ` +with the following configuration: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + # ... + serializer: + enable_annotations: true + + .. code-block:: xml + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + // ... + 'serializer' => array( + 'enable_annotations' => true, + ), + )); + +Enabling the Metadata Cache +--------------------------- + +.. versionadded:: 2.7 + Serializer was introduced in Symfony 2.7. + +Metadata used by the Serializer component such as groups can be cached to +enhance application performance. Any service implementing the ``Doctrine\Common\Cache\Cache`` +interface can be used. + +A service leveraging `APCu`_ (and APC for PHP < 5.5) is built-in. + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config_prod.yml + framework: + # ... + serializer: + cache: serializer.mapping.cache.apc + + .. code-block:: xml + + + + + + + + .. code-block:: php + + // app/config/config_prod.php + $container->loadFromExtension('framework', array( + // ... + 'serializer' => array( + 'cache' => 'serializer.mapping.cache.apc', + ), + )); + +Going Further with the Serializer Component +------------------------------------------- + +`DunglasApiBundle`_ provides an API system supporting `JSON-LD`_ and `Hydra Core Vocabulary`_ +hypermedia formats. It is built on top of the Symfony Framework and its Serializer +component. It provides custom normalizers and a custom encoder, custom metadata +and a caching system. + +If you want to leverage the full power of the Symfony Serializer component, +take a look at how this bundle works. + +.. _`APCu`: https://github.com/krakjoe/apcu +.. _`DunglasApiBundle`: https://github.com/dunglas/DunglasApiBundle +.. _`JSON-LD`: http://json-ld.org +.. _`Hydra Core Vocabulary`: http://hydra-cg.com