[Validator] Finished inline documentation of ExecutionContext[Interface]

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 <bschussek@gmail.com>
+ *
+ * @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($node);
-            $this->nodeStack->push($this->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 null;
-
-            return $poppedNode;
         }
 
+        $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;
-    }
 }

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 <bschussek@gmail.com>
  */
 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.
+     * Returns the root value of the object 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.
      *
      * 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.
+     * 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
-     * If the validated value is neither of these, for example if the validator
+     * belong to any structural element.
-     * has been called with a plain value and constraint, this method returns
-     * null.
      *
      * @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
+     * {@link ClassBasedInterface}, this method returns null.
-     * current node, 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
+     * {@link PropertyMetadataInterface}, this method returns null.
-     * current node, 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:
      *
-     * <pre>
+     *     (Person)---($address: Address)---($street: string)
-     * (Person)---($address: Address)---($street: string)
-     * </pre>
      *
      * When the <tt>Person</tt> instance is passed to the validator, the
      * property path is initially empty. When the <tt>$address</tt> 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 <tt>$addresses</tt> and contains an array
-     * of <tt>Address</tt> instance, the property path generated for the
+     * of <tt>Address</tt> instances, the property path generated for the
      * <tt>$street</tt> 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 = '');
 }

src/Symfony/Component/Validator/Mapping/AdHocMetadata.php

@@ -18,7 +18,7 @@ use Symfony\Component\Validator\Exception\ValidatorException;
  * @since  %%NextVersion%%
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
-class ValueMetadata extends ElementMetadata
+class AdHocMetadata extends ElementMetadata
 {
     public function __construct(array $constraints)
     {

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(