diff --git a/components/index.rst b/components/index.rst index 43aa14e5e40..8f8cdc08f35 100644 --- a/components/index.rst +++ b/components/index.rst @@ -28,7 +28,7 @@ The Components property_access/index routing/index security/index - serializer + serializer/index stopwatch templating/index translation/index diff --git a/components/map.rst.inc b/components/map.rst.inc index ee9c34ba884..a7dd126cb9b 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -140,9 +140,10 @@ * :doc:`/components/security/authorization` * :doc:`/components/security/secure_tools` -* **Serializer** +* :doc:`/components/serializer/index` - * :doc:`/components/serializer` + * :doc:`/components/serializer/introduction` + * :doc:`/components/serializer/encoders` * **Stopwatch** diff --git a/components/serializer/encoders.rst b/components/serializer/encoders.rst new file mode 100644 index 00000000000..9b268273d35 --- /dev/null +++ b/components/serializer/encoders.rst @@ -0,0 +1,63 @@ +.. index:: + single: Serializer, Encoders + +Encoders +======== + +Encoders basically turn **arrays** into **formats** and vice versa. +They implement +:class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface` for +encoding (array to format) and +:class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface` for +decoding (format to array). + +You can add new encoders to a Serializer instance by using its second constructor argument:: + + use Symfony\Component\Serializer\Serializer; + use Symfony\Component\Serializer\Encoder\XmlEncoder; + use Symfony\Component\Serializer\Encoder\JsonEncoder; + + $encoders = array(new XmlEncoder(), new JsonEncoder()); + $serializer = new Serializer(array(), $encoders); + +Built-in Encoders +----------------- + +Two encoders are used in the example above: + +* :class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder` to encode/decode XML +* :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` to encode/decode JSON + +The ``XmlEncoder`` +~~~~~~~~~~~~~~~~~~ + +This encoder transforms arrays into XML and vice versa. + +For example, take an object normalized as following:: + + array('foo' => array(1, 2), 'bar' => true); + +The ``XmlEncoder`` will encode this object like that:: + + + + 1 + 2 + 1 + + +Be aware that this encoder will consider keys beginning with ``@`` as attributes:: + + $encoder = new XmlEncoder(); + $encoder->encode(array('foo' => array('@bar' => 'value'))); + // will return: + // + // + // + // + +The ``JsonEncoder`` +~~~~~~~~~~~~~~~~~~~ + +The ``JsonEncoder`` is much simpler and is based on the PHP +:phpfunction:`json_encode` and :phpfunction:`json_decode` functions. diff --git a/components/serializer/index.rst b/components/serializer/index.rst new file mode 100644 index 00000000000..d2493f383ed --- /dev/null +++ b/components/serializer/index.rst @@ -0,0 +1,8 @@ +Serializer +========== + +.. toctree:: + :maxdepth: 2 + + introduction + encoders diff --git a/components/serializer.rst b/components/serializer/introduction.rst similarity index 98% rename from components/serializer.rst rename to components/serializer/introduction.rst index c8354d9713e..d67bcbdaca0 100644 --- a/components/serializer.rst +++ b/components/serializer/introduction.rst @@ -44,7 +44,7 @@ Usage Using the Serializer component is really simple. You just need to set up the :class:`Symfony\\Component\\Serializer\\Serializer` specifying -which Encoders and Normalizer are going to be available:: +which encoders and normalizers are going to be available:: use Symfony\Component\Serializer\Serializer; use Symfony\Component\Serializer\Encoder\XmlEncoder; @@ -57,10 +57,14 @@ which Encoders and Normalizer are going to be available:: $serializer = new Serializer($normalizers, $encoders); The preferred normalizer is the -:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`, but other -normalizers are available. -To read more about them, refer to the `Normalizers`_ section of this page. All -the examples shown below use the ``ObjectNormalizer``. +:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`, +but other normalizers are available. All the examples shown below use +the ``ObjectNormalizer``. + +.. seealso:: + + Read the dedicated sections to learn more about :doc:`/components/serializer/encoders` + and `Normalizers`_. Serializing an Object --------------------- diff --git a/cookbook/index.rst b/cookbook/index.rst index f6ee4386b87..687e9fb7933 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -26,7 +26,7 @@ The Cookbook request/index routing/index security/index - serializer + serializer/index service_container/index session/index symfony1 diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index bbef8f68661..207ab5c1334 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -187,9 +187,10 @@ * :doc:`/cookbook/security/securing_services` * :doc:`/cookbook/security/access_control` -* **Serializer** +* :doc:`/cookbook/serializer/index` - * :doc:`/cookbook/serializer` + * :doc:`/cookbook/serializer/introduction` + * :doc:`/cookbook/serializer/custom_encoders` * :doc:`/cookbook/service_container/index` diff --git a/cookbook/serializer/custom_encoders.rst b/cookbook/serializer/custom_encoders.rst new file mode 100644 index 00000000000..5cacea05984 --- /dev/null +++ b/cookbook/serializer/custom_encoders.rst @@ -0,0 +1,97 @@ +.. index:: + single: Serializer; Custom encoders + +How to Create your Custom Encoder +================================= + +The :doc:`Serializer Component ` uses Normalizers +to transform any data to an array that can be then converted in whatever +data-structured language you want thanks to Encoders. + +The Component provides several built-in encoders that are described +:doc:`in their own section ` but you may want +to use another language not supported. + +Creating a new encoder +---------------------- + +Imagine you want to serialize and deserialize Yaml. For that you'll have to +create your own encoder that may use the +:doc:`Yaml Component `:: + + namespace AppBundle\Encoder; + + use Symfony\Component\Serializer\Encoder\DecoderInterface; + use Symfony\Component\Serializer\Encoder\EncoderInterface; + use Symfony\Component\Yaml\Yaml; + + class YamlEncoder implements EncoderInterface, DecoderInterface + { + public function encode($data, $format, array $context = array()) + { + return Yaml::dump($data); + } + + public function supportsEncoding($format) + { + return 'yaml' === $format; + } + + public function decode($data, $format, array $context = array()) + { + return Yaml::parse($data); + } + + public function supportsDecoding($format) + { + return 'yaml' === $format; + } + } + +Registering it in your app +-------------------------- + +If you use the Symfony Framework then you probably want to register this encoder +as a service in your app. Then you only need to tag it as `serializer.encoder` and it will be +injected in the Serializer. + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/services.yml + services: + app.encoder.yaml: + class: AppBundle\Encoder\YamlEncoder + tags: + - { name: serializer.encoder } + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/services.php + $container + ->register( + 'app.encoder.yaml', + 'AppBundle\Encoder\YamlEncoder' + ) + ->addTag('serializer.encoder') + ; + +Now you'll be able to serialize and deserialize Yaml! + +.. _tracker: https://github.com/symfony/symfony/issues diff --git a/cookbook/serializer/index.rst b/cookbook/serializer/index.rst new file mode 100644 index 00000000000..7578be22c61 --- /dev/null +++ b/cookbook/serializer/index.rst @@ -0,0 +1,8 @@ +Serializer +========== + +.. toctree:: + :maxdepth: 2 + + introduction + custom_encoders diff --git a/cookbook/serializer.rst b/cookbook/serializer/introduction.rst similarity index 98% rename from cookbook/serializer.rst rename to cookbook/serializer/introduction.rst index 00e8d70f939..74d9cb77183 100644 --- a/cookbook/serializer.rst +++ b/cookbook/serializer/introduction.rst @@ -1,16 +1,16 @@ .. index:: - single: Serializer + single: Serializer; Introduction How to Use the Serializer ========================= Serializing and deserializing to and from objects and different formats (e.g. JSON or XML) is a very complex topic. Symfony comes with a -:doc:`Serializer Component `, which gives you some +:doc:`Serializer Component `, which gives you some 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 `. +and encoders by reading the :doc:`Serializer Component `. Activating the Serializer ------------------------- diff --git a/redirection_map b/redirection_map index faf3e0fd638..cfa75bed667 100644 --- a/redirection_map +++ b/redirection_map @@ -10,6 +10,7 @@ /cookbook/email /cookbook/email/email /cookbook/gmail /cookbook/email/gmail /cookbook/console /components/console +/cookbook/serializer /cookbook/serializer/introduction /cookbook/tools/autoloader /components/class_loader /cookbook/tools/finder /components/finder /cookbook/service_container/parentservices /components/dependency_injection/parentservices @@ -26,6 +27,7 @@ /components/yaml /components/yaml/introduction /components/templating /components/templating/introduction /components/filesystem /components/filesystem/introduction +/components/serializer /components/serializer/introduction /cmf/reference/configuration/block /cmf/bundles/block/configuration /cmf/reference/configuration/content /cmf/bundles/content/configuration /cmf/reference/configuration/core /cmf/bundles/core/configuration diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index 2d847f0a1aa..0dbaf95b312 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -946,7 +946,7 @@ serializer.encoder The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface` and :class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface`. -For more details, see :doc:`/cookbook/serializer`. +For more details, see :doc:`/cookbook/serializer/introduction`. .. _reference-dic-tags-serializer-normalizer: @@ -958,7 +958,7 @@ serializer.normalizer The class that's tagged should implement the :class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface` and :class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface`. -For more details, see :doc:`/cookbook/serializer`. +For more details, see :doc:`/cookbook/serializer/introduction`. swiftmailer.default.plugin --------------------------