merged branch beberlei/SerializerOptions (PR #6797)

This PR was merged into the master branch.

Commits
-------

fcabadf Fix JsonDecode to work on PHP 5.3, update the CHANGELOG.md
b6bdb45 Completly refactor the Serializer Options Pull Request to push context information directly and avoid state and dependencies between SerializerInterface and encoders/normalizers.
ef652e2 Added context to JsonEncoder
eacb7e2 Rename $options to $context, as it makes the intent much more clear.
8854b85 Fix CS issues, removed global options
9c54a4b [Serializer] Allow options to be passed to SerialiizerInterface#serialize and #unserialize. Thsee options are available to all encoders/decoders/normalizers that implement SerializerAwareInterface.

Discussion
----------

[2.2] [Serializer] Configurable Serializer

Bug fix: no
Feature addition: yes
Backwards compatibility break: yes
Symfony2 tests pass: yes
Fixes the following tickets: #4907, #4938
License of the code: MIT
Todo:

This is an extension of GH-6574 that removes the context state in favor of passing this information around.

---------------------------------------------------------------------------

by beberlei at 2013-01-18T13:12:39Z

@fabpot @lsmith I think this is how it should work from an OOP/OOD perpesctive, avoiding the context state. This makes for a much cleaner code and dependency graph.

---------------------------------------------------------------------------

by lsmith77 at 2013-01-18T14:14:37Z

makes sense. anything fancier would lose this components simplicity which IMHO is the main benefit versus JMS serializer.

---------------------------------------------------------------------------

by fabpot at 2013-01-18T14:26:25Z

Looks very good. :+1:

---------------------------------------------------------------------------

by beberlei at 2013-01-18T14:37:32Z

I need to fix the failures with the JsonEncoder and then this is good to merge

---------------------------------------------------------------------------

by stof at 2013-01-18T14:40:21Z

you also need to update the CHANGELOG of the component

---------------------------------------------------------------------------

by beberlei at 2013-01-18T23:17:57Z

Fixed, only the Redis Profiler problem still failing the Travis builds. Also I updated the CHANGELOG.md.

@fabpot  Good to merge from my POV

---------------------------------------------------------------------------

by stof at 2013-01-18T23:27:59Z

@beberlei see #6804 for the Redis profiler issue

Author: fabpot

CHANGELOG.md

@@ -1,6 +1,16 @@
 CHANGELOG
 =========
 
+2.2.0
+-----
+
+ * All Serializer, Normalizer and Encoder interfaces have been
+   modified to include an optional ``$context`` array parameter.
+ * The XML Root name can now be configured with the ``xml_root_name``
+   parameter in the context option to the ``XmlEncoder``.
+ * Options to ``json_encode`` and ``json_decode`` can be passed through
+   the context options of ``JsonEncode`` and ``JsonDecode`` encoder/decoders.
+
 2.1.0
 -----
 

Encoder/ChainDecoder.php

@@ -34,9 +34,9 @@ public function __construct(array $decoders = array())
     /**
      * {@inheritdoc}
      */
-    final public function decode($data, $format)
+    final public function decode($data, $format, array $context = array())
     {
-        return $this->getDecoder($format)->decode($data, $format);
+        return $this->getDecoder($format)->decode($data, $format, $context);
     }
 
     /**

Encoder/ChainEncoder.php

@@ -35,9 +35,9 @@ public function __construct(array $encoders = array())
     /**
      * {@inheritdoc}
      */
-    final public function encode($data, $format)
+    final public function encode($data, $format, array $context = array())
     {
-        return $this->getEncoder($format)->encode($data, $format);
+        return $this->getEncoder($format)->encode($data, $format, $context);
     }
 
     /**

Encoder/DecoderInterface.php

@@ -23,10 +23,11 @@ interface DecoderInterface
      *
      * @param scalar $data   Data to decode
      * @param string $format Format name
+     * @param array  $context options that decoders have access to.
      *
      * @return mixed
      */
-    public function decode($data, $format);
+    public function decode($data, $format, array $context = array());
 
     /**
      * Checks whether the serializer can decode from given format

Encoder/EncoderInterface.php

@@ -23,10 +23,11 @@ interface EncoderInterface
      *
      * @param mixed  $data   Data to encode
      * @param string $format Format name
+     * @param array  $context options that normalizers/encoders have access to.
      *
      * @return scalar
      */
-    public function encode($data, $format);
+    public function encode($data, $format, array $context = array());
 
     /**
      * Checks whether the serializer can encode to given format

Encoder/JsonDecode.php

@@ -21,6 +21,7 @@ class JsonDecode implements DecoderInterface
     private $associative;
     private $recursionDepth;
     private $lastError = JSON_ERROR_NONE;
+    protected $serializer;
 
     public function __construct($associative = false, $depth = 512)
     {
@@ -48,9 +49,20 @@ public function getLastError()
      *
      * @return mixed
      */
-    public function decode($data, $format)
+    public function decode($data, $format, array $context = array())
     {
-        $decodedData = json_decode($data, $this->associative, $this->recursionDepth);
+        $context = $this->resolveContext($context);
+
+        $associative    = $context['json_decode_associative'];
+        $recursionDepth = $context['json_decode_recursion_depth'];
+        $options        = $context['json_decode_options'];
+
+        if (version_compare(PHP_VERSION, '5.4.0') >= 0) {
+            $decodedData = json_decode($data, $associative, $recursionDepth, $options);
+        } else {
+            $decodedData = json_decode($data, $associative, $recursionDepth);
+        }
+
         $this->lastError = json_last_error();
 
         return $decodedData;
@@ -63,4 +75,21 @@ public function supportsDecoding($format)
     {
         return JsonEncoder::FORMAT === $format;
     }
+
+    /**
+     * Merge the default options of the Json Decoder with the passed context.
+     *
+     * @param array $context
+     * @return array
+     */
+    private function resolveContext(array $context)
+    {
+        $defaultOptions = array(
+            'json_decode_associative' => $this->associative,
+            'json_decode_recursion_depth' => $this->recursionDepth,
+            'json_decode_options' => 0
+        );
+
+        return array_merge($defaultOptions, $context);
+    }
 }

Encoder/JsonEncode.php

@@ -41,14 +41,13 @@ public function getLastError()
     /**
      * Encodes PHP data to a JSON string
      *
-     * @param mixed  $data
-     * @param string $format
-     *
-     * @return string
+     * {@inheritdoc}
      */
-    public function encode($data, $format)
+    public function encode($data, $format, array $context = array())
     {
-        $encodedJson = json_encode($data, $this->options);
+        $context = $this->resolveContext($context);
+
+        $encodedJson = json_encode($data, $context['json_encode_options']);
         $this->lastError = json_last_error();
 
         return $encodedJson;
@@ -61,4 +60,15 @@ public function supportsEncoding($format)
     {
         return JsonEncoder::FORMAT === $format;
     }
+
+    /**
+     * Merge default json encode options with context.
+     *
+     * @param array $context
+     * @return array
+     */
+    private function resolveContext(array $context = array())
+    {
+        return array_merge(array('json_encode_options' => $this->options), $context);
+    }
 }

Encoder/JsonEncoder.php

@@ -59,17 +59,17 @@ public function getLastDecodingError()
     /**
      * {@inheritdoc}
      */
-    public function encode($data, $format)
+    public function encode($data, $format, array $context = array())
     {
-        return $this->encodingImpl->encode($data, self::FORMAT);
+        return $this->encodingImpl->encode($data, self::FORMAT, $context);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function decode($data, $format)
+    public function decode($data, $format, array $context = array())
     {
-        return $this->decodingImpl->decode($data, self::FORMAT);
+        return $this->decodingImpl->decode($data, self::FORMAT, $context);
     }
 
     /**

Encoder/XmlEncoder.php

@@ -26,24 +26,36 @@ class XmlEncoder extends SerializerAwareEncoder implements EncoderInterface, Dec
     private $format;
     private $rootNodeName = 'response';
 
+    /**
+     * Construct new XmlEncoder and allow to change the root node element name.
+     *
+     * @param string $rootNodeName
+     */
+    public function __construct($rootNodeName = 'response')
+    {
+        $this->rootNodeName = $rootNodeName;
+    }
+
     /**
      * {@inheritdoc}
      */
-    public function encode($data, $format)
+    public function encode($data, $format, array $context = array())
     {
         if ($data instanceof \DOMDocument) {
             return $data->saveXML();
         }
 
+        $xmlRootNodeName = $this->resolveXmlRootName($context);
+
         $this->dom = new \DOMDocument();
         $this->format = $format;
 
         if (null !== $data && !is_scalar($data)) {
-            $root = $this->dom->createElement($this->rootNodeName);
+            $root = $this->dom->createElement($xmlRootNodeName);
             $this->dom->appendChild($root);
-            $this->buildXml($root, $data);
+            $this->buildXml($root, $data, $xmlRootNodeName);
         } else {
-            $this->appendNode($this->dom, $data, $this->rootNodeName);
+            $this->appendNode($this->dom, $data, $xmlRootNodeName);
         }
 
         return $this->dom->saveXML();
@@ -52,7 +64,7 @@ public function encode($data, $format)
     /**
      * {@inheritdoc}
      */
-    public function decode($data, $format)
+    public function decode($data, $format, array $context = array())
     {
         $internalErrors = libxml_use_internal_errors(true);
         $disableEntities = libxml_disable_entity_loader(true);
@@ -269,12 +281,13 @@ private function parseXml($node)
      *
      * @param DOMNode      $parentNode
      * @param array|object $data       data
+     * @param string       $xmlRootNodeName
      *
      * @return Boolean
      *
      * @throws UnexpectedValueException
      */
-    private function buildXml($parentNode, $data)
+    private function buildXml($parentNode, $data, $xmlRootNodeName)
     {
         $append = true;
 
@@ -310,21 +323,24 @@ private function buildXml($parentNode, $data)
 
             return $append;
         }
+
         if (is_object($data)) {
             $data = $this->serializer->normalize($data, $this->format);
             if (null !== $data && !is_scalar($data)) {
-                return $this->buildXml($parentNode, $data);
+                return $this->buildXml($parentNode, $data, $xmlRootNodeName);
             }
+
             // top level data object was normalized into a scalar
             if (!$parentNode->parentNode->parentNode) {
                 $root = $parentNode->parentNode;
                 $root->removeChild($parentNode);
 
-                return $this->appendNode($root, $data, $this->rootNodeName);
+                return $this->appendNode($root, $data, $xmlRootNodeName);
             }
 
             return $this->appendNode($parentNode, $data, 'data');
         }
+
         throw new UnexpectedValueException('An unexpected value could not be serialized: '.var_export($data, true));
     }
 
@@ -376,7 +392,7 @@ private function needsCdataWrapping($val)
     private function selectNodeType($node, $val)
     {
         if (is_array($val)) {
-            return $this->buildXml($node, $val);
+            return $this->buildXml($node, $val, null);
         } elseif ($val instanceof \SimpleXMLElement) {
             $child = $this->dom->importNode(dom_import_simplexml($val), true);
             $node->appendChild($child);
@@ -399,4 +415,15 @@ private function selectNodeType($node, $val)
 
         return true;
     }
+
+    /**
+     * Get real XML root node name, taking serializer options into account.
+     */
+    private function resolveXmlRootName(array $context = array())
+    {
+        return isset($context['xml_root_node_name'])
+            ? $context['xml_root_node_name']
+            : $this->rootNodeName;
+    }
+
 }

Normalizer/CustomNormalizer.php

@@ -19,18 +19,18 @@ class CustomNormalizer extends SerializerAwareNormalizer implements NormalizerIn
     /**
      * {@inheritdoc}
      */
-    public function normalize($object, $format = null)
+    public function normalize($object, $format = null, array $context = array())
     {
-        return $object->normalize($this->serializer, $format);
+        return $object->normalize($this->serializer, $format, $context);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function denormalize($data, $class, $format = null)
+    public function denormalize($data, $class, $format = null, array $context = array())
     {
         $object = new $class;
-        $object->denormalize($this->serializer, $data, $format);
+        $object->denormalize($this->serializer, $data, $format, $context);
 
         return $object;
     }