Merge remote branch 'Seldaek/serializer'

* Seldaek/serializer:
  [Serializer] Some more privates
  [Serializer] Move private methods below protected ones
  [Serializer] Added @api annotations
  [Serializer] Added docblocks for NormalizableInterface
  [Serializer] add methods to the SerializerInterface
  [Serializer] Added docblock
  [Serializer] Switched most protected to private or final

src/Symfony/Component/Serializer/Encoder/EncoderInterface.php

@@ -26,6 +26,7 @@ interface EncoderInterface
      * @param mixed $data data to encode
      * @param string $format format to encode to
      * @return string
+     * @api
      */
     function encode($data, $format);
 
@@ -35,6 +36,7 @@ interface EncoderInterface
      * @param string $data data to decode
      * @param string $format format to decode from
      * @return mixed
+     * @api
      */
     function decode($data, $format);
 
@@ -42,6 +44,7 @@ interface EncoderInterface
      * Sets the owning Serializer object
      *
      * @param SerializerInterface $serializer
+     * @api
      */
     function setSerializer(SerializerInterface $serializer);
 
@@ -49,6 +52,7 @@ interface EncoderInterface
      * Gets the owning Serializer object
      *
      * @return SerializerInterface
+     * @api
      */
     function getSerializer();
 }

src/Symfony/Component/Serializer/Encoder/XmlEncoder.php

@@ -22,9 +22,9 @@ use Symfony\Component\Serializer\SerializerInterface;
  */
 class XmlEncoder extends AbstractEncoder
 {
-    protected $dom;
+    private $dom;
-    protected $format;
+    private $format;
-    protected $rootNodeName = 'response';
+    private $rootNodeName = 'response';
 
     /**
      * {@inheritdoc}
@@ -78,13 +78,83 @@ class XmlEncoder extends AbstractEncoder
         return $this->rootNodeName;
     }
 
+    /**
+     * @param DOMNode $node
+     * @param string $val
+     * @return Boolean
+     */
+    final protected function appendXMLString($node, $val)
+    {
+        if (strlen($val) > 0) {
+            $frag = $this->dom->createDocumentFragment();
+            $frag->appendXML($val);
+            $node->appendChild($frag);
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * @param DOMNode $node
+     * @param string $val
+     * @return Boolean
+     */
+    final protected function appendText($node, $val)
+    {
+        $nodeText = $this->dom->createTextNode($val);
+        $node->appendChild($nodeText);
+
+        return true;
+    }
+
+    /**
+     * @param DOMNode $node
+     * @param string $val
+     * @return Boolean
+     */
+    final protected function appendCData($node, $val)
+    {
+        $nodeText = $this->dom->createCDATASection($val);
+        $node->appendChild($nodeText);
+
+        return true;
+    }
+
+    /**
+     * @param DOMNode $node
+     * @param DOMDocumentFragment $fragment
+     * @return Boolean
+     */
+    final protected function appendDocumentFragment($node, $fragment)
+    {
+        if ($fragment instanceof \DOMDocumentFragment) {
+            $node->appendChild($fragment);
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Checks the name is avalid xml element name
+     * @param string $name
+     * @return Boolean
+     */
+    final protected function isElementNameValid($name)
+    {
+        return $name &&
+            false === strpos($name, ' ') &&
+            preg_match('#^[\pL_][\pL0-9._-]*$#ui', $name);
+    }
+
     /**
      * Parse the input SimpleXmlElement into an array
      *
      * @param SimpleXmlElement $node xml to parse
      * @return array
      */
-    protected function parseXml($node)
+    private function parseXml($node)
     {
         $data = array();
         foreach ($node->children() as $key => $subnode) {
@@ -126,7 +196,7 @@ class XmlEncoder extends AbstractEncoder
      * @param array|object $data data
      * @return bool
      */
-    protected function buildXml($parentNode, $data)
+    private function buildXml($parentNode, $data)
     {
         $append = true;
 
@@ -183,7 +253,7 @@ class XmlEncoder extends AbstractEncoder
      * @param  $nodename
      * @return void
      */
-    protected function appendNode($parentNode, $data, $nodeName, $key = null)
+    private function appendNode($parentNode, $data, $nodeName, $key = null)
     {
         $node = $this->dom->createElement($nodeName);
         if (null !== $key) {
@@ -204,7 +274,7 @@ class XmlEncoder extends AbstractEncoder
      * @param mixed $val
      * @return Boolean
      */
-    protected function selectNodeType($node, $val)
+    private function selectNodeType($node, $val)
     {
         if (is_array($val)) {
             return $this->buildXml($node, $val);
@@ -228,74 +298,4 @@ class XmlEncoder extends AbstractEncoder
 
         return true;
     }
-
-    /**
-     * @param DOMNode $node
-     * @param string $val
-     * @return Boolean
-     */
-    protected function appendXMLString($node, $val)
-    {
-        if (strlen($val) > 0) {
-            $frag = $this->dom->createDocumentFragment();
-            $frag->appendXML($val);
-            $node->appendChild($frag);
-            return true;
-        }
-
-        return false;
-    }
-
-    /**
-     * @param DOMNode $node
-     * @param string $val
-     * @return Boolean
-     */
-    protected function appendText($node, $val)
-    {
-        $nodeText = $this->dom->createTextNode($val);
-        $node->appendChild($nodeText);
-
-        return true;
-    }
-
-    /**
-     * @param DOMNode $node
-     * @param string $val
-     * @return Boolean
-     */
-    protected function appendCData($node, $val)
-    {
-        $nodeText = $this->dom->createCDATASection($val);
-        $node->appendChild($nodeText);
-
-        return true;
-    }
-
-    /**
-     * @param DOMNode $node
-     * @param DOMDocumentFragment $fragment
-     * @return Boolean
-     */
-    protected function appendDocumentFragment($node, $fragment)
-    {
-        if ($fragment instanceof \DOMDocumentFragment) {
-            $node->appendChild($fragment);
-            return true;
-        }
-
-        return false;
-    }
-
-    /**
-     * Checks the name is avalid xml element name
-     * @param string $name
-     * @return Boolean
-     */
-    protected function isElementNameValid($name)
-    {
-        return $name &&
-            false === strpos($name, ' ') &&
-            preg_match('#^[\pL_][\pL0-9._-]*$#ui', $name);
-    }
 }

src/Symfony/Component/Serializer/Normalizer/GetSetMethodNormalizer.php

@@ -133,7 +133,7 @@ class GetSetMethodNormalizer extends AbstractNormalizer
      * @param ReflectionMethod $method the method to check
      * @return Boolean whether the method is a getter.
      */
-    protected function isGetMethod(\ReflectionMethod $method)
+    private function isGetMethod(\ReflectionMethod $method)
     {
         return (
             0 === strpos($method->getName(), 'get') &&

src/Symfony/Component/Serializer/Normalizer/NormalizableInterface.php

@@ -21,6 +21,35 @@ namespace Symfony\Component\Serializer\Normalizer;
  */
 interface NormalizableInterface
 {
+    /**
+     * Normalizes the object into an array of scalars|arrays.
+     *
+     * It is important to understand that the normalize() call should normalize
+     * recursively all child objects of the implementor.
+     *
+     * @param NormalizerInterface $normalizer The normalizer is given so that you
+     *   can use it to normalize objects contained within this object, eventually
+     *   grabbing the serializer from it to access other normalizers.
+     * @param string|null $format The format is optionally given to be able to normalize differently
+     *   based on different output formats.
+     * @param array|null $properties If provided, this is a (subset) list of
+     *   properties that should be exported from the object.
+     * @return array|scalar
+     */
     function normalize(NormalizerInterface $normalizer, $format, $properties = null);
+
+    /**
+     * Denormalizes the object back from an array of scalars|arrays.
+     *
+     * It is important to understand that the normalize() call should denormalize
+     * recursively all child objects of the implementor.
+     *
+     * @param NormalizerInterface $normalizer The normalizer is given so that you
+     *   can use it to denormalize objects contained within this object, eventually
+     *   grabbing the serializer from it to access other normalizers.
+     * @param array|scalar $data The data from which to re-create the object.
+     * @param string|null $format The format is optionally given to be able to denormalize differently
+     *   based on different input formats.
+     */
     function denormalize(NormalizerInterface $normalizer, $data, $format = null);
 }

src/Symfony/Component/Serializer/Normalizer/NormalizerInterface.php

@@ -27,6 +27,7 @@ interface NormalizerInterface
      * @param string $format format the normalization result will be encoded as
      * @param array $properties a list of properties to extract, if null all properties are returned
      * @return array|scalar
+     * @api
      */
     function normalize($object, $format, $properties = null);
 
@@ -37,6 +38,7 @@ interface NormalizerInterface
      * @param string $class the expected class to instantiate
      * @param string $format format the given data was extracted from
      * @return object
+     * @api
      */
     function denormalize($data, $class, $format = null);
 
@@ -46,6 +48,7 @@ interface NormalizerInterface
      * @param ReflectionClass $class
      * @param string $format format the given data was extracted from
      * @return Boolean
+     * @api
      */
     function supports(\ReflectionClass $class, $format = null);
 
@@ -53,6 +56,7 @@ interface NormalizerInterface
      * Sets the owning Serializer object
      *
      * @param SerializerInterface $serializer
+     * @api
      */
     function setSerializer(SerializerInterface $serializer);
 
@@ -60,6 +64,7 @@ interface NormalizerInterface
      * Gets the owning Serializer object
      *
      * @return SerializerInterface
+     * @api
      */
     function getSerializer();
 }

src/Symfony/Component/Serializer/Serializer.php

@@ -28,13 +28,17 @@ use Symfony\Component\Serializer\Encoder\EncoderInterface;
  */
 class Serializer implements SerializerInterface
 {
-    protected $normalizers = array();
+    private $normalizers = array();
-    protected $encoders = array();
+    private $encoders = array();
-    protected $normalizerCache = array();
+    private $normalizerCache = array();
 
-    public function isStructuredType($val)
+    /**
+     * @param mixed $value value to test
+     * @return Boolean whether the type is a structured type (array + objects)
+     */
+    public function isStructuredType($value)
     {
-        return null !== $val && !is_scalar($val);
+        return null !== $value && !is_scalar($value);
     }
 
     /**
@@ -127,17 +131,26 @@ class Serializer implements SerializerInterface
         return $this->encoders[$format]->decode($data, $format);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function addNormalizer(NormalizerInterface $normalizer)
     {
         $this->normalizers[] = $normalizer;
         $normalizer->setSerializer($this);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getNormalizers()
     {
         return $this->normalizers;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function removeNormalizer(NormalizerInterface $normalizer)
     {
         unset($this->normalizers[array_search($normalizer, $this->normalizers, true)]);

src/Symfony/Component/Serializer/SerializerInterface.php

@@ -3,6 +3,7 @@
 namespace Symfony\Component\Serializer;
 
 use Symfony\Component\Serializer\Encoder\EncoderInterface;
+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
 
 /*
  * This file is part of the Symfony framework.
@@ -26,6 +27,7 @@ interface SerializerInterface
      * @param mixed $data any data
      * @param string $format format name
      * @return string
+     * @api
      */
     function serialize($data, $format);
 
@@ -35,6 +37,7 @@ interface SerializerInterface
      * @param mixed $data data to normalize
      * @param string $format format name, present to give the option to normalizers to act differently based on formats
      * @return array|scalar
+     * @api
      */
     function normalize($data, $format);
 
@@ -64,6 +67,7 @@ interface SerializerInterface
      * @param mixed $data data to encode
      * @param string $format format name
      * @return array|scalar
+     * @api
      */
     function encode($data, $format);
 
@@ -73,9 +77,25 @@ interface SerializerInterface
      * @param string $data data to decode
      * @param string $format format name
      * @return mixed
+     * @api
      */
     function decode($data, $format);
 
+    /**
+     * @param NormalizerInterface $normalizer
+     */
+    function addNormalizer(NormalizerInterface $normalizer);
+
+    /**
+     * @return array[]NormalizerInterface
+     */
+    function getNormalizers();
+
+    /**
+     * @param NormalizerInterface $normalizer
+     */
+    function removeNormalizer(NormalizerInterface $normalizer);
+
     /**
      * @param string $format format name
      * @param EncoderInterface $encoder