diff --git a/src/Symfony/Component/Validator/Validator/ContextualValidator.php b/src/Symfony/Component/Validator/Validator/ContextualValidator.php index cd969cc5b1..b250278941 100644 --- a/src/Symfony/Component/Validator/Validator/ContextualValidator.php +++ b/src/Symfony/Component/Validator/Validator/ContextualValidator.php @@ -24,7 +24,9 @@ use Symfony\Component\Validator\NodeTraverser\NodeTraverserInterface; use Symfony\Component\Validator\Util\PropertyPath; /** - * @since %%NextVersion%% + * Default implementation of {@link ContextualValidatorInterface}. + * + * @since 2.5 * @author Bernhard Schussek */ class ContextualValidator implements ContextualValidatorInterface @@ -44,6 +46,15 @@ class ContextualValidator implements ContextualValidatorInterface */ private $metadataFactory; + /** + * Creates a validator for the given context. + * + * @param ExecutionContextInterface $context The execution context + * @param NodeTraverserInterface $nodeTraverser The node traverser + * @param MetadataFactoryInterface $metadataFactory The factory for fetching + * the metadata of validated + * objects + */ public function __construct(ExecutionContextInterface $context, NodeTraverserInterface $nodeTraverser, MetadataFactoryInterface $metadataFactory) { $this->context = $context; @@ -53,13 +64,19 @@ class ContextualValidator implements ContextualValidatorInterface $this->metadataFactory = $metadataFactory; } - public function atPath($subPath) + /** + * {@inheritdoc} + */ + public function atPath($path) { - $this->defaultPropertyPath = $this->context->getPropertyPath($subPath); + $this->defaultPropertyPath = $this->context->getPropertyPath($path); return $this; } + /** + * {@inheritdoc} + */ public function validate($value, $constraints = null, $groups = null) { if (null === $constraints) { @@ -84,6 +101,9 @@ class ContextualValidator implements ContextualValidatorInterface return $this; } + /** + * {@inheritdoc} + */ public function validateProperty($object, $propertyName, $groups = null) { $classMetadata = $this->metadataFactory->getMetadataFor($object); @@ -118,6 +138,9 @@ class ContextualValidator implements ContextualValidatorInterface return $this; } + /** + * {@inheritdoc} + */ public function validatePropertyValue($object, $propertyName, $value, $groups = null) { $classMetadata = $this->metadataFactory->getMetadataFor($object); @@ -151,6 +174,21 @@ class ContextualValidator implements ContextualValidatorInterface return $this; } + /** + * {@inheritdoc} + */ + public function getViolations() + { + return $this->context->getViolations(); + } + + /** + * Normalizes the given group or list of groups to an array. + * + * @param mixed $groups The groups to normalize + * + * @return array A group array + */ protected function normalizeGroups($groups) { if (is_array($groups)) { @@ -159,9 +197,4 @@ class ContextualValidator implements ContextualValidatorInterface return array($groups); } - - public function getViolations() - { - return $this->context->getViolations(); - } } diff --git a/src/Symfony/Component/Validator/Validator/ContextualValidatorInterface.php b/src/Symfony/Component/Validator/Validator/ContextualValidatorInterface.php index e384228d7c..83b5d07120 100644 --- a/src/Symfony/Component/Validator/Validator/ContextualValidatorInterface.php +++ b/src/Symfony/Component/Validator/Validator/ContextualValidatorInterface.php @@ -15,17 +15,24 @@ use Symfony\Component\Validator\Constraint; use Symfony\Component\Validator\ConstraintViolationListInterface; /** - * @since %%NextVersion%% + * A validator in a specific execution context. + * + * @since 2.5 * @author Bernhard Schussek */ interface ContextualValidatorInterface { /** - * @param string $subPath + * Appends the given path to the property path of the context. + * + * If called multiple times, the path will always be reset to the context's + * original path with the given path appended to it. + * + * @param string $path The path to append * * @return ContextualValidatorInterface This validator */ - public function atPath($subPath); + public function atPath($path); /** * Validates a value against a constraint or a list of constraints. @@ -33,46 +40,50 @@ interface ContextualValidatorInterface * If no constraint is passed, the constraint * {@link \Symfony\Component\Validator\Constraints\Valid} is assumed. * - * @param mixed $value The value to validate. - * @param Constraint|Constraint[] $constraints The constraint(s) to validate against. - * @param array|null $groups The validation groups to validate. + * @param mixed $value The value to validate + * @param Constraint|Constraint[] $constraints The constraint(s) to validate + * against + * @param array|null $groups The validation groups to + * validate. If none is given, + * "Default" is assumed * * @return ContextualValidatorInterface This validator */ public function validate($value, $constraints = null, $groups = null); /** - * Validates a property of a value against its current value. + * Validates a property of an object against the constraints specified + * for this property. * - * The accepted values depend on the {@link MetadataFactoryInterface} - * implementation. - * - * @param mixed $object The value containing the property. - * @param string $propertyName The name of the property to validate. - * @param array|null $groups The validation groups to validate. + * @param object $object The object + * @param string $propertyName The name of the validated property + * @param array|null $groups The validation groups to validate. If + * none is given, "Default" is assumed * * @return ContextualValidatorInterface This validator */ public function validateProperty($object, $propertyName, $groups = null); /** - * Validate a property of a value against a potential value. + * Validates a value against the constraints specified for an object's + * property. * - * The accepted values depend on the {@link MetadataFactoryInterface} - * implementation. - * - * @param string $object The value containing the property. - * @param string $propertyName The name of the property to validate - * @param string $value The value to validate against the - * constraints of the property. - * @param array|null $groups The validation groups to validate. + * @param object $object The object + * @param string $propertyName The name of the property + * @param mixed $value The value to validate against the + * property's constraints + * @param array|null $groups The validation groups to validate. If + * none is given, "Default" is assumed * * @return ContextualValidatorInterface This validator */ public function validatePropertyValue($object, $propertyName, $value, $groups = null); /** - * @return ConstraintViolationListInterface + * Returns the violations that have been generated so far in the context + * of the validator. + * + * @return ConstraintViolationListInterface The constraint violations */ public function getViolations(); } diff --git a/src/Symfony/Component/Validator/Validator/LegacyValidator.php b/src/Symfony/Component/Validator/Validator/LegacyValidator.php index 9ecf522f85..eae4746e88 100644 --- a/src/Symfony/Component/Validator/Validator/LegacyValidator.php +++ b/src/Symfony/Component/Validator/Validator/LegacyValidator.php @@ -17,9 +17,14 @@ use Symfony\Component\Validator\Constraints\Valid; use Symfony\Component\Validator\ValidatorInterface as LegacyValidatorInterface; /** + * A validator that supports both the API of Symfony < 2.5 and Symfony 2.5+. + * * @since 2.5 * @author Bernhard Schussek * + * @see \Symfony\Component\Validator\ValidatorInterface + * @see \Symfony\Component\Validator\Validator\ValidatorInterface + * * @deprecated Implemented for backwards compatibility with Symfony < 2.5. * To be removed in Symfony 3.0. */ diff --git a/src/Symfony/Component/Validator/Validator/Validator.php b/src/Symfony/Component/Validator/Validator/Validator.php index fad080155a..a73a72ebb5 100644 --- a/src/Symfony/Component/Validator/Validator/Validator.php +++ b/src/Symfony/Component/Validator/Validator/Validator.php @@ -17,7 +17,9 @@ use Symfony\Component\Validator\NodeTraverser\NodeTraverserInterface; use Symfony\Component\Validator\MetadataFactoryInterface; /** - * @since %%NextVersion%% + * Default implementation of {@link ValidatorInterface}. + * + * @since 2.5 * @author Bernhard Schussek */ class Validator implements ValidatorInterface @@ -37,6 +39,16 @@ class Validator implements ValidatorInterface */ protected $metadataFactory; + /** + * Creates a new validator. + * + * @param ExecutionContextFactoryInterface $contextFactory The factory for + * creating new contexts + * @param NodeTraverserInterface $nodeTraverser The node traverser + * @param MetadataFactoryInterface $metadataFactory The factory for + * fetching the metadata + * of validated objects + */ public function __construct(ExecutionContextFactoryInterface $contextFactory, NodeTraverserInterface $nodeTraverser, MetadataFactoryInterface $metadataFactory) { $this->contextFactory = $contextFactory; @@ -84,6 +96,9 @@ class Validator implements ValidatorInterface return $this->metadataFactory->hasMetadataFor($object); } + /** + * {@inheritdoc} + */ public function validate($value, $constraints = null, $groups = null) { return $this->startContext($value) @@ -91,6 +106,9 @@ class Validator implements ValidatorInterface ->getViolations(); } + /** + * {@inheritdoc} + */ public function validateProperty($object, $propertyName, $groups = null) { return $this->startContext($object) @@ -98,6 +116,9 @@ class Validator implements ValidatorInterface ->getViolations(); } + /** + * {@inheritdoc} + */ public function validatePropertyValue($object, $propertyName, $value, $groups = null) { return $this->startContext($object) diff --git a/src/Symfony/Component/Validator/Validator/ValidatorInterface.php b/src/Symfony/Component/Validator/Validator/ValidatorInterface.php index 124514a1ff..163d1b6ca6 100644 --- a/src/Symfony/Component/Validator/Validator/ValidatorInterface.php +++ b/src/Symfony/Component/Validator/Validator/ValidatorInterface.php @@ -16,7 +16,9 @@ use Symfony\Component\Validator\ConstraintViolationListInterface; use Symfony\Component\Validator\Context\ExecutionContextInterface; /** - * @since %%NextVersion%% + * Validates PHP values against constraints. + * + * @since 2.5 * @author Bernhard Schussek */ interface ValidatorInterface @@ -27,60 +29,91 @@ interface ValidatorInterface * If no constraint is passed, the constraint * {@link \Symfony\Component\Validator\Constraints\Valid} is assumed. * - * @param mixed $value The value to validate. - * @param Constraint|Constraint[] $constraints The constraint(s) to validate against. - * @param array|null $groups The validation groups to validate. + * @param mixed $value The value to validate + * @param Constraint|Constraint[] $constraints The constraint(s) to validate + * against + * @param array|null $groups The validation groups to + * validate. If none is given, + * "Default" is assumed * - * @return ConstraintViolationListInterface A list of constraint violations. If the - * list is empty, validation succeeded. + * @return ConstraintViolationListInterface A list of constraint violations. + * If the list is empty, validation + * succeeded */ public function validate($value, $constraints = null, $groups = null); /** - * Validates a property of a value against its current value. + * Validates a property of an object against the constraints specified + * for this property. * - * The accepted values depend on the {@link MetadataFactoryInterface} - * implementation. + * @param object $object The object + * @param string $propertyName The name of the validated property + * @param array|null $groups The validation groups to validate. If + * none is given, "Default" is assumed * - * @param mixed $object The value containing the property. - * @param string $propertyName The name of the property to validate. - * @param array|null $groups The validation groups to validate. - * - * @return ConstraintViolationListInterface A list of constraint violations. If the - * list is empty, validation succeeded. + * @return ConstraintViolationListInterface A list of constraint violations. + * If the list is empty, validation + * succeeded */ public function validateProperty($object, $propertyName, $groups = null); /** - * Validate a property of a value against a potential value. + * Validates a value against the constraints specified for an object's + * property. * - * The accepted values depend on the {@link MetadataFactoryInterface} - * implementation. + * @param object $object The object + * @param string $propertyName The name of the property + * @param mixed $value The value to validate against the + * property's constraints + * @param array|null $groups The validation groups to validate. If + * none is given, "Default" is assumed * - * @param string $object The value containing the property. - * @param string $propertyName The name of the property to validate - * @param string $value The value to validate against the - * constraints of the property. - * @param array|null $groups The validation groups to validate. - * - * @return ConstraintViolationListInterface A list of constraint violations. If the - * list is empty, validation succeeded. + * @return ConstraintViolationListInterface A list of constraint violations. + * If the list is empty, validation + * succeeded */ public function validatePropertyValue($object, $propertyName, $value, $groups = null); /** - * @return ContextualValidatorInterface + * Starts a new validation context and returns a validator for that context. + * + * The returned validator collects all violations generated within its + * context. You can access these violations with the + * {@link ContextualValidatorInterface::getViolations()} method. + * + * @return ContextualValidatorInterface The validator for the new context */ public function startContext(); /** - * @param ExecutionContextInterface $context + * Returns a validator in the given execution context. * - * @return ContextualValidatorInterface + * The returned validator adds all generated violations to the given + * context. + * + * @param ExecutionContextInterface $context The execution context + * + * @return ContextualValidatorInterface The validator for that context */ public function inContext(ExecutionContextInterface $context); + /** + * Returns the metadata for an object. + * + * @param object $object The object + * + * @return \Symfony\Component\Validator\Mapping\MetadataInterface The metadata + * + * @throws \Symfony\Component\Validator\Exception\NoSuchMetadataException If no metadata exists + */ public function getMetadataFor($object); + /** + * Returns whether the validator has metadata for an object. + * + * @param object $object The object + * + * @return Boolean Whether metadata exists for that object + */ public function hasMetadataFor($object); }