Skip to content
Browse files

added some more doc comments

  • Loading branch information...
1 parent 1b0abde commit 64f84404b173cd67afc991fe593aac6b8758fdb7 @schmittjoh committed
View
18 DependencyInjection/HandlerFactoryInterface.php
@@ -1,18 +0,0 @@
-<?php
-
-namespace JMS\SerializerBundle\DependencyInjection;
-
-use Symfony\Component\DependencyInjection\ContainerBuilder;
-use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
-
-interface HandlerFactoryInterface
-{
- const TYPE_SERIALIZATION = 1;
- const TYPE_DESERIALIZATION = 2;
- const TYPE_ALL = 3;
-
- function getConfigKey();
- function addConfiguration(ArrayNodeDefinition $builder);
- function getType(array $config);
- function getHandlerId(ContainerBuilder $container, array $config);
-}
View
18 Serializer/Construction/ObjectConstructorInterface.php
@@ -21,7 +21,25 @@
use JMS\SerializerBundle\Serializer\VisitorInterface;
use JMS\SerializerBundle\Metadata\ClassMetadata;
+/**
+ * Implementations of this interface construct new objects during deserialization.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
interface ObjectConstructorInterface
{
+ /**
+ * Constructs a new object.
+ *
+ * Implementations could for example create a new object calling "new", use
+ * "unserialize" techniques, reflection, or other means.
+ *
+ * @param VisitorInterface $visitor
+ * @param ClassMetadata $metadata
+ * @param mixed $data
+ * @param array $type ["name" => string, "params" => array]
+ *
+ * @return object
+ */
function construct(VisitorInterface $visitor, ClassMetadata $metadata, $data, array $type);
}
View
46 Serializer/GraphNavigator.php
@@ -28,6 +28,14 @@
use JMS\SerializerBundle\Exception\InvalidArgumentException;
use JMS\SerializerBundle\Serializer\Exclusion\ExclusionStrategyInterface;
+/**
+ * Handles traversal along the object graph.
+ *
+ * This class handles traversal along the graph, and calls different methods
+ * on visitors, or custom handlers to process its nodes.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
final class GraphNavigator
{
const DIRECTION_SERIALIZATION = 1;
@@ -43,13 +51,25 @@
private $customHandlers = array();
private $visiting;
+ /**
+ * Parses a direction string to one of the direction constants.
+ *
+ * @param string $dirStr
+ *
+ * @return integer
+ */
public static function parseDirection($dirStr)
{
- if ( ! defined($constant = 'JMS\SerializerBundle\Serializer\GraphNavigator::DIRECTION_'.strtoupper($dirStr))) {
- throw new \InvalidArgumentException(sprintf('The direction "%s" does not exist.', $dirStr));
- }
+ switch (strtolower($dirStr)) {
+ case 'serialization':
+ return self::DIRECTION_SERIALIZATION;
- return constant($constant);
+ case 'deserialization':
+ return self::DIRECTION_DESERIALIZATION;
+
+ default:
+ throw new \InvalidArgumentException(sprintf('The direction "%s" does not exist.', $dirStr));
+ }
}
public function __construct($direction, MetadataFactoryInterface $metadataFactory, $format, HandlerRegistryInterface $handlerRegistry, ObjectConstructorInterface $objectConstructor, ExclusionStrategyInterface $exclusionStrategy = null, EventDispatcherInterface $dispatcher = null)
@@ -64,6 +84,15 @@ public function __construct($direction, MetadataFactoryInterface $metadataFactor
$this->visiting = new \SplObjectStorage();
}
+ /**
+ * Called for each node of the graph that is being traversed.
+ *
+ * @param mixed $data the data depends on the direction, and type of visitor
+ * @param array|null $type array has the format ["name" => string, "params" => array]
+ * @param VisitorInterface $visitor
+ *
+ * @return mixed the return value depends on the direction, and type of visitor
+ */
public function accept($data, array $type = null, VisitorInterface $visitor)
{
// determine type if not given
@@ -189,6 +218,15 @@ public function accept($data, array $type = null, VisitorInterface $visitor)
}
}
+ /**
+ * Detaches an object from the visiting map.
+ *
+ * Use this method if you like to re-visit an object which is already
+ * being visited. Be aware that you might cause an endless loop if you
+ * use this inappropriately.
+ *
+ * @param object $object
+ */
public function detachObject($object)
{
if (null === $object) {
View
6 Serializer/Handler/ConstraintViolationHandler.php
@@ -70,7 +70,7 @@ public function serializeListToYml(YamlSerializationVisitor $visitor, Constraint
return $visitor->visitArray(iterator_to_array($list), $type);
}
- public function serializeViolationToXml(VisitorInterface $visitor, ConstraintViolation $violation, array $type = null)
+ public function serializeViolationToXml(XmlSerializationVisitor $visitor, ConstraintViolation $violation, array $type = null)
{
if (null === $visitor->document) {
$visitor->document = $visitor->createDocument(null, null, false);
@@ -88,7 +88,7 @@ public function serializeViolationToXml(VisitorInterface $visitor, ConstraintVio
$messageNode->appendChild($visitor->document->createCDATASection($violation->getMessage()));
}
- public function serializeViolationToJson(VisitorInterface $visitor, ConstraintViolation $violation, array $type = null)
+ public function serializeViolationToJson(GenericSerializationVisitor $visitor, ConstraintViolation $violation, array $type = null)
{
$data = array(
'property_path' => $violation->getPropertyPath(),
@@ -102,7 +102,7 @@ public function serializeViolationToJson(VisitorInterface $visitor, ConstraintVi
return $data;
}
- public function serializeViolationToYml(VisitorInterface $visitor, ConstraintViolation $violaton, array $type = null)
+ public function serializeViolationToYml(YamlSerializationVisitor $visitor, ConstraintViolation $violaton, array $type = null)
{
return $this->serializeViolationToJson($visitor, $violation);
}
View
6 Serializer/Serializer.php
@@ -102,6 +102,9 @@ public function deserialize($data, $type, $format)
return $visitorResult;
}
+ /**
+ * @return VisitorInterface
+ */
protected function getDeserializationVisitor($format)
{
if (!isset($this->deserializationVisitors[$format])) {
@@ -111,6 +114,9 @@ protected function getDeserializationVisitor($format)
return $this->deserializationVisitors[$format];
}
+ /**
+ * @return VisitorInterface
+ */
protected function getSerializationVisitor($format)
{
if (!isset($this->serializationVisitors[$format])) {
View
23 Serializer/SerializerInterface.php
@@ -18,8 +18,31 @@
namespace JMS\SerializerBundle\Serializer;
+/**
+ * Serializer Interface.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
interface SerializerInterface
{
+ /**
+ * Serializes the given data to the specified output format.
+ *
+ * @param object|array|scalar $data
+ * @param string $format
+ *
+ * @return string
+ */
function serialize($data, $format);
+
+ /**
+ * Deserializes the given data to the specified type.
+ *
+ * @param string $data
+ * @param string $type
+ * @param string $format
+ *
+ * @return object|array|scalar
+ */
function deserialize($data, $type, $format);
}
View
11 Serializer/TypeParser.php
@@ -21,6 +21,11 @@
private $next;
private $pointer = 0;
+ /**
+ * @param string $type
+ *
+ * @return array of the format ["name" => string, "params" => array]
+ */
public function parse($type)
{
if (empty($type)) {
@@ -29,7 +34,7 @@ public function parse($type)
$this->tokenize($type);
- $parsedType = $this->Type();
+ $parsedType = $this->parseType();
if (null !== $this->next) {
throw new \InvalidArgumentException(sprintf('Expected end of type, but got %s (%s) at position %d.', $this->getTokenName($this->next[0]), json_encode($this->next[2]), $this->next[1]));
}
@@ -37,7 +42,7 @@ public function parse($type)
return $parsedType;
}
- private function Type()
+ private function parseType()
{
$this->match(self::T_NAME);
$typeName = $this->token[0];
@@ -50,7 +55,7 @@ private function Type()
$params = array();
do {
if ($this->isNextToken(self::T_NAME)) {
- $params[] = $this->Type();
+ $params[] = $this->parseType();
} else if ($this->isNextToken(self::T_STRING)) {
$this->moveNext();
$params[] = $this->token[0];
View
94 Serializer/VisitorInterface.php
@@ -21,18 +21,112 @@
use JMS\SerializerBundle\Metadata\ClassMetadata;
use JMS\SerializerBundle\Metadata\PropertyMetadata;
+/**
+ * Interface for visitors.
+ *
+ * This contains the minimal set of values that must be supported for any
+ * output format.
+ *
+ * @author Johannes M. Schmitt <schmittjoh@gmail.com>
+ */
interface VisitorInterface
{
+ /**
+ * Allows visitors to convert the input data to a different representation
+ * before the actual serialization/deserialization process starts.
+ *
+ * @param mixed $data
+ *
+ * @return mixed
+ */
function prepare($data);
+
+ /**
+ * @param mixed $data
+ * @param array $type
+ *
+ * @return mixed
+ */
function visitString($data, array $type);
+
+ /**
+ * @param mixed $data
+ * @param array $type
+ *
+ * @return mixed
+ */
function visitBoolean($data, array $type);
+
+ /**
+ * @param mixed $data
+ * @param array $type
+ *
+ * @return mixed
+ */
function visitDouble($data, array $type);
+
+ /**
+ * @param mixed $data
+ * @param array $type
+ *
+ * @return mixed
+ */
function visitInteger($data, array $type);
+
+ /**
+ * @param mixed $data
+ * @param array $type
+ *
+ * @return mixed
+ */
function visitArray($data, array $type);
+
+ /**
+ * Called before the properties of the object are being visited.
+ *
+ * @param ClassMetadata $metadata
+ * @param mixed $data
+ * @param array $type
+ *
+ * @return void
+ */
function startVisitingObject(ClassMetadata $metadata, $data, array $type);
+
+ /**
+ * @param PropertyMetadata $metadata
+ * @param mixed $data
+ *
+ * @return void
+ */
function visitProperty(PropertyMetadata $metadata, $data);
+
+ /**
+ * Called after all properties of the object have been visited.
+ *
+ * @param ClassMetadata $metadata
+ * @param mixed $data
+ * @param array $type
+ *
+ * @return mixed
+ */
function endVisitingObject(ClassMetadata $metadata, $data, array $type);
+
+ /**
+ * Called before serialization/deserialization starts.
+ *
+ * @param GraphNavigator $navigator
+ *
+ * @return void
+ */
function setNavigator(GraphNavigator $navigator);
+
+ /**
+ * @return GraphNavigator
+ */
function getNavigator();
+
+ /**
+ * @return object|array|scalar
+ */
function getResult();
}
View
9 Serializer/XmlSerializationVisitor.php
@@ -276,17 +276,14 @@ private function visitNumeric($data, array $type)
}
/**
- * Checks the name is a valid xml element name
+ * Checks that the name is a valid XML element name.
*
* @param string $name
*
- * @return Boolean
+ * @return boolean
*/
private function isElementNameValid($name)
{
- return $name &&
- false === strpos($name, ' ') &&
- preg_match('#^[\pL_][\pL0-9._-]*$#ui', $name);
+ return $name && false === strpos($name, ' ') && preg_match('#^[\pL_][\pL0-9._-]*$#ui', $name);
}
-
}
View
14 Twig/SerializerExtension.php
@@ -22,14 +22,14 @@
/**
* Serializer helper twig extension
- *
+ *
* Basically provides access to JMSSerializer from Twig
*/
-class SerializerExtension extends \Twig_Extension
+class SerializerExtension extends \Twig_Extension
{
protected $serializer;
- public function getName()
+ public function getName()
{
return 'jms_serializer';
}
@@ -39,14 +39,18 @@ public function __construct(SerializerInterface $serializer)
$this->serializer = $serializer;
}
- public function getFilters()
+ public function getFilters()
{
return array(
'serialize' => new \Twig_Filter_Method($this, 'serialize'),
);
}
- public function serialize($object, $type = 'json')
+ /**
+ * @param object $object
+ * @param string $type
+ */
+ public function serialize($object, $type = 'json')
{
return $this->serializer->serialize($object, $type);
}

0 comments on commit 64f8440

Please sign in to comment.
Something went wrong with that request. Please try again.