diff --git a/src/Symfony/Component/Validator/Context/ExecutionContext.php b/src/Symfony/Component/Validator/Context/ExecutionContext.php index 80af8392c5..bc6abc39b1 100644 --- a/src/Symfony/Component/Validator/Context/ExecutionContext.php +++ b/src/Symfony/Component/Validator/Context/ExecutionContext.php @@ -23,21 +23,39 @@ use Symfony\Component\Validator\Validator\ValidatorInterface; use Symfony\Component\Validator\Violation\ConstraintViolationBuilder; /** - * @since %%NextVersion%% + * The context used and created by {@link ExecutionContextManager}. + * + * @since 2.5 * @author Bernhard Schussek + * + * @see ExecutionContextInterface */ class ExecutionContext implements ExecutionContextInterface { + /** + * The root value of the validated object graph. + * + * @var mixed + */ private $root; + /** + * The violations generated in the current context. + * + * @var ConstraintViolationList + */ private $violations; /** + * The current node under validation. + * * @var Node */ private $node; /** + * The trace of nodes from the root node to the current node. + * * @var \SplStack */ private $nodeStack; @@ -73,25 +91,39 @@ class ExecutionContext implements ExecutionContextInterface $this->nodeStack = new \SplStack(); } + /** + * Sets the values of the context to match the given node. + * + * Internally, all nodes are stored on a stack and can be removed from that + * stack using {@link popNode()}. + * + * @param Node $node The currently validated node + */ public function pushNode(Node $node) { - if (null !== $this->node) { - $this->nodeStack->push($this->node); - } - + $this->nodeStack->push($node); $this->node = $node; } + /** + * Sets the values of the context to match the previous node. + * + * The current node is removed from the internal stack and returned. + * + * @return Node|null The currently validated node or null, if no node was + * on the stack + */ public function popNode() { - $poppedNode = $this->node; - + // Nothing to do if the stack is empty if (0 === count($this->nodeStack)) { - $this->node = null; - - return $poppedNode; + return null; } + $poppedNode = $this->node; + + // After removing the last node, the stack is empty and the node + // is null if (1 === count($this->nodeStack)) { $this->nodeStack->pop(); $this->node = null; @@ -105,6 +137,9 @@ class ExecutionContext implements ExecutionContextInterface return $poppedNode; } + /** + * {@inheritdoc} + */ public function addViolation($message, array $parameters = array()) { $this->violations->add(new ConstraintViolation( @@ -119,6 +154,9 @@ class ExecutionContext implements ExecutionContextInterface )); } + /** + * {@inheritdoc} + */ public function buildViolation($message, array $parameters = array()) { return new ConstraintViolationBuilder( @@ -133,31 +171,57 @@ class ExecutionContext implements ExecutionContextInterface ); } + /** + * {@inheritdoc} + */ public function getViolations() { return $this->violations; } + /** + * {@inheritdoc} + */ + public function getValidator() + { + return $this->validator; + } + + /** + * {@inheritdoc} + */ public function getRoot() { return $this->root; } + /** + * {@inheritdoc} + */ public function getValue() { return $this->node ? $this->node->value : null; } + /** + * {@inheritdoc} + */ public function getMetadata() { return $this->node ? $this->node->metadata : null; } + /** + * {@inheritdoc} + */ public function getGroup() { return $this->groupManager->getCurrentGroup(); } + /** + * {@inheritdoc} + */ public function getClassName() { $metadata = $this->getMetadata(); @@ -165,6 +229,9 @@ class ExecutionContext implements ExecutionContextInterface return $metadata instanceof ClassBasedInterface ? $metadata->getClassName() : null; } + /** + * {@inheritdoc} + */ public function getPropertyName() { $metadata = $this->getMetadata(); @@ -172,18 +239,13 @@ class ExecutionContext implements ExecutionContextInterface return $metadata instanceof PropertyMetadataInterface ? $metadata->getPropertyName() : null; } + /** + * {@inheritdoc} + */ public function getPropertyPath($subPath = '') { $propertyPath = $this->node ? $this->node->propertyPath : ''; return PropertyPath::append($propertyPath, $subPath); } - - /** - * @return ValidatorInterface - */ - public function getValidator() - { - return $this->validator; - } } diff --git a/src/Symfony/Component/Validator/Context/ExecutionContextInterface.php b/src/Symfony/Component/Validator/Context/ExecutionContextInterface.php index b6eeb73d35..5ff0a81724 100644 --- a/src/Symfony/Component/Validator/Context/ExecutionContextInterface.php +++ b/src/Symfony/Component/Validator/Context/ExecutionContextInterface.php @@ -11,52 +11,121 @@ namespace Symfony\Component\Validator\Context; +use Symfony\Component\Validator\Constraints\GroupSequence; use Symfony\Component\Validator\ConstraintViolationListInterface; use Symfony\Component\Validator\Mapping\MetadataInterface; use Symfony\Component\Validator\Validator\ValidatorInterface; +use Symfony\Component\Validator\Violation\ConstraintViolationBuilderInterface; /** - * @since %%NextVersion%% + * The context of a validation run. + * + * The context collects all violations generated during the validation. By + * default, validators execute all validations in a new context: + * + * $violations = $validator->validateObject($object); + * + * When you make another call to the validator, while the validation is in + * progress, the violations will be isolated from each other: + * + * public function validate($value, Constraint $constraint) + * { + * $validator = $this->context->getValidator(); + * + * // The violations are not added to $this->context + * $violations = $validator->validateObject($value); + * } + * + * However, if you want to add the violations to the current context, use the + * {@link ValidatorInterface::inContext()} method: + * + * public function validate($value, Constraint $constraint) + * { + * $validator = $this->context->getValidator(); + * + * // The violations are added to $this->context + * $validator + * ->inContext($this->context) + * ->validateObject($value) + * ; + * } + * + * Additionally, the context provides information about the current state of + * the validator, such as the currently validated class, the name of the + * currently validated property and more. These values change over time, so you + * cannot store a context and expect that the methods still return the same + * results later on. + * + * @since 2.5 * @author Bernhard Schussek */ interface ExecutionContextInterface { /** + * Adds a violation at the current node of the validation graph. + * + * @param string $message The error message + * @param array $parameters The parameters substituted in the error message + */ + public function addViolation($message, array $parameters = array()); + + /** + * Returns a builder for adding a violation with extended information. + * + * Call {@link ConstraintViolationBuilderInterface::addViolation()} to + * add the violation when you're done with the configuration: + * + * $context->buildViolation('Please enter a number between %min% and %max.') + * ->setParameter('%min%', 3) + * ->setParameter('%max%', 10) + * ->setTranslationDomain('number_validation') + * ->addViolation(); + * + * @param string $message The error message + * @param array $parameters The parameters substituted in the error message + * + * @return ConstraintViolationBuilderInterface The violation builder + */ + public function buildViolation($message, array $parameters = array()); + + /** + * Returns the violations generated in this context. + * + * @return ConstraintViolationListInterface The constraint violations + */ + public function getViolations(); + + /** + * Returns the validator. + * + * Useful if you want to validate additional constraints: + * + * public function validate($value, Constraint $constraint) + * { + * $validator = $this->context->getValidator(); + * + * $violations = $validator->validateValue($value, new Length(array('min' => 3))); + * + * if (count($violations) > 0) { + * // ... + * } + * } + * * @return ValidatorInterface */ public function getValidator(); /** - * Adds a violation at the current node of the validation graph. - * - * @param string $message The error message. - * @param array $parameters The parameters substituted in the error message. - * - * @api - */ - public function addViolation($message, array $parameters = array()); - - public function buildViolation($message); - - /** - * Returns the violations generated by the validator so far. - * - * @return ConstraintViolationListInterface The constraint violation list. - * - * @api - */ - public function getViolations(); - - /** - * Returns the value at which validation was started in the object graph. + * Returns the root value of the object graph. * * The validator, when given an object, traverses the properties and * related objects and their properties. The root of the validation is the - * object from which the traversal started. + * object at which the traversal started. * - * The current value is returned by {@link getValue}. + * The current value is returned by {@link getValue()}. * - * @return mixed The root value of the validation. + * @return mixed|null The root value of the validation or null, if no value + * is currently being validated */ public function getRoot(); @@ -64,9 +133,10 @@ interface ExecutionContextInterface * Returns the value that the validator is currently validating. * * If you want to retrieve the object that was originally passed to the - * validator, use {@link getRoot}. + * validator, use {@link getRoot()}. * - * @return mixed The currently validated value. + * @return mixed|null The currently validated value or null, if no value is + * currently being validated */ public function getValue(); @@ -77,21 +147,22 @@ interface ExecutionContextInterface * {@link Mapping\ClassMetadata} instance if the current value is an object, * a {@link Mapping\PropertyMetadata} instance if the current value is * the value of a property and a {@link Mapping\GetterMetadata} instance if - * the validated value is the result of a getter method. - * - * If the validated value is neither of these, for example if the validator - * has been called with a plain value and constraint, this method returns - * null. + * the validated value is the result of a getter method. The metadata can + * also be an {@link Mapping\AdHocMetadata} if the current value does not + * belong to any structural element. * * @return MetadataInterface|null The metadata of the currently validated - * value. + * value or null, if no value is currently + * being validated */ public function getMetadata(); /** * Returns the validation group that is currently being validated. * - * @return string The current validation group. + * @return string|GroupSequence|null The current validation group or null, + * if no value is currently being + * validated */ public function getGroup(); @@ -99,10 +170,10 @@ interface ExecutionContextInterface * Returns the class name of the current node. * * If the metadata of the current node does not implement - * {@link ClassBasedInterface} or if no metadata is available for the - * current node, this method returns null. + * {@link ClassBasedInterface}, this method returns null. * - * @return string|null The class name or null, if no class name could be found. + * @return string|null The class name or null, if no class name could be + * found */ public function getClassName(); @@ -110,10 +181,10 @@ interface ExecutionContextInterface * Returns the property name of the current node. * * If the metadata of the current node does not implement - * {@link PropertyMetadataInterface} or if no metadata is available for the - * current node, this method returns null. + * {@link PropertyMetadataInterface}, this method returns null. * - * @return string|null The property name or null, if no property name could be found. + * @return string|null The property name or null, if no property name could + * be found */ public function getPropertyName(); @@ -123,9 +194,7 @@ interface ExecutionContextInterface * * For example, take the following object graph: * - * 
-     * (Person)---($address: Address)---($street: string)
-     *
+ * (Person)---($address: Address)---($street: string) * * When the Person instance is passed to the validator, the * property path is initially empty. When the $address property @@ -137,16 +206,16 @@ interface ExecutionContextInterface * Indices of arrays or objects implementing the {@link \ArrayAccess} * interface are enclosed in brackets. For example, if the property in * the previous example is $addresses and contains an array - * of Address instance, the property path generated for the + * of Address instances, the property path generated for the * $street property of one of these addresses is for example * "addresses[0].street". * * @param string $subPath Optional. The suffix appended to the current - * property path. + * property path * * @return string The current property path. The result may be an empty * string if the validator is currently validating the - * root value of the validation graph. + * root value of the validation graph */ public function getPropertyPath($subPath = ''); } diff --git a/src/Symfony/Component/Validator/Mapping/ValueMetadata.php b/src/Symfony/Component/Validator/Mapping/AdHocMetadata.php similarity index 97% rename from src/Symfony/Component/Validator/Mapping/ValueMetadata.php rename to src/Symfony/Component/Validator/Mapping/AdHocMetadata.php index 230e5dd947..a7b836d341 100644 --- a/src/Symfony/Component/Validator/Mapping/ValueMetadata.php +++ b/src/Symfony/Component/Validator/Mapping/AdHocMetadata.php @@ -18,7 +18,7 @@ use Symfony\Component\Validator\Exception\ValidatorException; * @since %%NextVersion%% * @author Bernhard Schussek */ -class ValueMetadata extends ElementMetadata +class AdHocMetadata extends ElementMetadata { public function __construct(array $constraints) { diff --git a/src/Symfony/Component/Validator/Validator/AbstractValidator.php b/src/Symfony/Component/Validator/Validator/AbstractValidator.php index 69f48ca7d0..c57473e751 100644 --- a/src/Symfony/Component/Validator/Validator/AbstractValidator.php +++ b/src/Symfony/Component/Validator/Validator/AbstractValidator.php @@ -16,7 +16,7 @@ use Symfony\Component\Validator\Context\ExecutionContextInterface; use Symfony\Component\Validator\Exception\UnexpectedTypeException; use Symfony\Component\Validator\Exception\ValidatorException; use Symfony\Component\Validator\Mapping\ClassMetadataInterface; -use Symfony\Component\Validator\Mapping\ValueMetadata; +use Symfony\Component\Validator\Mapping\AdHocMetadata; use Symfony\Component\Validator\MetadataFactoryInterface; use Symfony\Component\Validator\Node\ClassNode; use Symfony\Component\Validator\Node\PropertyNode; @@ -165,7 +165,7 @@ abstract class AbstractValidator implements ValidatorInterface $constraints = array($constraints); } - $metadata = new ValueMetadata($constraints); + $metadata = new AdHocMetadata($constraints); $groups = $groups ? $this->normalizeGroups($groups) : $this->defaultGroups; $this->nodeTraverser->traverse(array(new ValueNode(