Permalink
Browse files

[Validator] Adding a significant amount of PHPDoc to the Validator co…

…mponent.
  • Loading branch information...
1 parent 9370e1c commit b309adcee229d358a62de30651ed488c37109573 @weaverryan weaverryan committed with fabpot Jan 16, 2011
View
@@ -30,6 +30,9 @@
{
const DEFAULT_GROUP = 'Default';
+ /**
+ * @var array
+ */
public $groups = array(self::DEFAULT_GROUP);
/**
View
@@ -17,18 +17,27 @@
private $messageTemplate;
private $messageParameters;
+ /**
+ * {@inheritDoc}
+ */
public function initialize(ValidationContext $context)
{
$this->context = $context;
$this->messageTemplate = '';
$this->messageParameters = array();
}
+ /**
+ * {@inheritDoc}
+ */
public function getMessageTemplate()
{
return $this->messageTemplate;
}
+ /**
+ * {@inheritDoc}
+ */
public function getMessageParameters()
{
return $this->messageParameters;
@@ -14,10 +14,20 @@
use Symfony\Component\Validator\ConstraintValidatorFactoryInterface;
use Symfony\Component\Validator\Constraint;
+/**
+ * Default implementation of the ConstraintValidatorFactoryInterface.
+ *
+ * This enforces the convention that the validatedBy() method on any
+ * Constrain will return the class name of the ConstraintValidator that
+ * should validate the Constraint.
+ */
class ConstraintValidatorFactory implements ConstraintValidatorFactoryInterface
{
protected $validators = array();
+ /**
+ * {@inheritDoc}
+ */
public function getInstance(Constraint $constraint)
{
$className = $constraint->validatedBy();
@@ -13,7 +13,18 @@
use Symfony\Component\Validator\Constraint;
+/**
+ * Specifies an object able to return the correct ConstraintValidatorInterface
+ * instance given a Constrain object.
+ */
interface ConstraintValidatorFactoryInterface
{
+ /**
+ * Given a Constrain, this returns the ConstraintValidatorInterface
+ * object that should be used to verify its validity.
+ *
+ * @param Constraint $constraint The source constraint
+ * @return ConstraintValidatorInterface
+ */
function getInstance(Constraint $constraint);
}
@@ -13,11 +13,27 @@
interface ConstraintValidatorInterface
{
+ /**
+ * Initialize the constraint validator.
+ *
+ * @param ValidationContext $context The current validation context
+ */
function initialize(ValidationContext $context);
+ /**
+ * @param mixed $value The value that should be validated
+ * @param Constraint $constraint The constrain for the validation
+ * @return boolean Whether or not the value is valid
+ */
function isValid($value, Constraint $constraint);
+ /**
+ * @return string
+ */
function getMessageTemplate();
+ /**
+ * @return array
+ */
function getMessageParameters();
}
View
@@ -11,6 +11,9 @@
* with this source code in the file LICENSE.
*/
+/**
+ * Represents a single violation of a constraint.
+ */
class ConstraintViolation
{
protected $messageTemplate;
@@ -28,16 +31,27 @@ public function __construct($messageTemplate, array $messageParameters, $root, $
$this->invalidValue = $invalidValue;
}
+ /**
+ * @return string
+ */
public function getMessageTemplate()
{
return $this->messageTemplate;
}
+ /**
+ * @return array
+ */
public function getMessageParameters()
{
return $this->messageParameters;
}
+ /**
+ * Returns the violation message.
+ *
+ * @return string
+ */
public function getMessage()
{
return str_replace(array_keys($this->messageParameters), array_values($this->messageParameters), $this->messageTemplate);
@@ -11,10 +11,16 @@
* with this source code in the file LICENSE.
*/
+/**
+ * An array-acting object that holds many ConstrainViolation instances.
+ */
class ConstraintViolationList implements \IteratorAggregate, \Countable
{
protected $violations = array();
+ /**
+ * @return string
+ */
public function __toString()
{
$string = '';
@@ -32,23 +38,39 @@ public function __toString()
return $string;
}
+ /**
+ * Add a ConstraintViolation to this list.
+ *
+ * @param ConstraintViolation $violation
+ */
public function add(ConstraintViolation $violation)
{
$this->violations[] = $violation;
}
+ /**
+ * Merge an existing ConstraintViolationList into this list.
+ *
+ * @param ConstraintViolationList $violations
+ */
public function addAll(ConstraintViolationList $violations)
{
foreach ($violations->violations as $violation) {
$this->violations[] = $violation;
}
}
+ /**
+ * @see IteratorAggregate
+ */
public function getIterator()
{
return new \ArrayIterator($this->violations);
}
+ /**
+ * @see Countable
+ */
public function count()
{
return count($this->violations);
View
@@ -20,6 +20,13 @@
use Symfony\Component\Validator\Mapping\ClassMetadata;
use Symfony\Component\Validator\Mapping\MemberMetadata;
+/**
+ * Responsible for walking over and initializing validation on different
+ * types of items.
+ *
+ * @author Fabien Potencier <fabien.potencier@symfony-project.com>
+ * @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
+ */
class GraphWalker
{
protected $context;
@@ -33,11 +40,23 @@ public function __construct($root, ClassMetadataFactoryInterface $metadataFactor
$this->metadataFactory = $metadataFactory;
}
+ /**
+ * @return ConstraintViolationList
+ */
public function getViolations()
{
return $this->context->getViolations();
}
+ /**
+ * Initialize validation on the given object using the given metadata
+ * instance and validation group.
+ *
+ * @param ClassMetadata $metadata
+ * @param object $object The object to validate
+ * @param string $group The validator group to use for validation
+ * @param string $propertyPath
+ */
public function walkClass(ClassMetadata $metadata, $object, $group, $propertyPath)
{
$this->context->setCurrentClass($metadata->getClassName());
View
@@ -16,6 +16,12 @@
use Symfony\Component\Validator\Exception\ConstraintDefinitionException;
use Symfony\Component\Validator\Exception\GroupDefinitionException;
+/**
+ * Represents all the configured constraints on a given class.
+ *
+ * @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
+ * @author Fabien Potencier <fabien.potencier@symfony-project.com>
+ */
class ClassMetadata extends ElementMetadata
{
public $name;
@@ -70,12 +76,12 @@ public function getClassName()
*
* For each class, the group "Default" is an alias for the group
* "<ClassName>", where <ClassName> is the non-namespaced name of the
- * class. All constraints implicitely or explicitely assigned to group
+ * class. All constraints implicitly or explicitly assigned to group
* "Default" belong to both of these groups, unless the class defines
* a group sequence.
*
* If a class defines a group sequence, validating the class in "Default"
- * will validate the group sequence. The constraints assinged to "Default"
+ * will validate the group sequence. The constraints assigned to "Default"
* can still be validated by validating the class in "<ClassName>".
*
* @return string The name of the default group
@@ -202,6 +208,7 @@ protected function addMemberMetadata(MemberMetadata $metadata)
* Returns all metadatas of members describing the given property
*
* @param string $property The name of the property
+ * @array of MemberMetadata
*/
public function getMemberMetadatas($property)
{
View
@@ -13,6 +13,15 @@
use Symfony\Component\Validator\Mapping\ClassMetadataFactoryInterface;
+/**
+ * The central object representing a single validation process.
+ *
+ * This object is used by the GraphWalker to initialize validation of different
+ * items and keep track of the violations.
+ *
+ * @author Fabien Potencier <fabien.potencier@symfony-project.com>
+ * @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
+ */
class ValidationContext
{
protected $root;
@@ -52,6 +61,9 @@ public function addViolation($message, array $params, $invalidValue)
));
}
+ /**
+ * @return ConstraintViolationList
+ */
public function getViolations()
{
return $this->violations;
@@ -102,11 +114,17 @@ public function getGroup()
return $this->group;
}
+ /**
+ * @return GraphWalker
+ */
public function getGraphWalker()
{
return $this->graphWalker;
}
+ /**
+ * @return ClassMetadataFactoryInterface
+ */
public function getClassMetadataFactory()
{
return $this->metadataFactory;
View
@@ -15,6 +15,15 @@
use Symfony\Component\Validator\Mapping\ClassMetadata;
use Symfony\Component\Validator\Mapping\ClassMetadataFactoryInterface;
+/**
+ * The default implementation of the ValidatorInterface.
+ *
+ * This service can be used to validate objects, properties and raw values
+ * against constraints.
+ *
+ * @author Fabien Potencier <fabien.potencier@symfony-project.com>
+ * @author Bernhard Schussek <bernhard.schussek@symfony-project.com>
+ */
class Validator implements ValidatorInterface
{
protected $metadataFactory;
@@ -29,6 +38,9 @@ public function __construct(
$this->validatorFactory = $validatorFactory;
}
+ /**
+ * {@inheritDoc}
+ */
public function validate($object, $groups = null)
{
$metadata = $this->metadataFactory->getClassMetadata(get_class($object));
@@ -40,6 +52,9 @@ public function validate($object, $groups = null)
return $this->validateGraph($object, $walk, $groups);
}
+ /**
+ * {@inheritDoc}
+ */
public function validateProperty($object, $property, $groups = null)
{
$metadata = $this->metadataFactory->getClassMetadata(get_class($object));
@@ -51,6 +66,9 @@ public function validateProperty($object, $property, $groups = null)
return $this->validateGraph($object, $walk, $groups);
}
+ /**
+ * {@inheritDoc}
+ */
public function validatePropertyValue($class, $property, $value, $groups = null)
{
$metadata = $this->metadataFactory->getClassMetadata($class);
@@ -62,6 +80,9 @@ public function validatePropertyValue($class, $property, $value, $groups = null)
return $this->validateGraph($class, $walk, $groups);
}
+ /**
+ * {@inheritDoc}
+ */
public function validateValue($value, Constraint $constraint, $groups = null)
{
$walk = function(GraphWalker $walker, $group) use ($constraint, $value) {
Oops, something went wrong.

0 comments on commit b309adc

Please sign in to comment.