[Validator] Refactored the GraphWalker into an implementation of the …

…Visitor design pattern.

With this refactoring comes a decoupling of the validator from the structure of
the underlying metadata. This way it is possible for Drupal to use the validator
for validating their Entity API by using their own metadata layer, which is not
modeled as classes and properties/getter methods.

CHANGELOG.md

@@ -6,6 +6,27 @@ CHANGELOG
 
  * added a CardScheme validator
  * added a Luhn validator
+ * moved @api-tags from `Validator` to `ValidatorInterface`
+ * moved @api-tags from `ConstraintViolation` to the new `ConstraintViolationInterface`
+ * moved @api-tags from `ConstraintViolationList` to the new `ConstraintViolationListInterface`
+ * moved @api-tags from `ExecutionContext` to the new `ExecutionContextInterface`
+ * [BC BREAK] `ConstraintValidatorInterface::initialize` is now type hinted against `ExecutionContextInterface` instead of `ExecutionContext`
+ * [BC BREAK] changed the visibility of the properties in `Validator` from protected to private
+ * deprecated `ClassMetadataFactoryInterface` in favor of the new `MetadataFactoryInterface`
+ * deprecated `ClassMetadataFactory::getClassMetadata` in favor of `getMetadataFor`
+ * created `MetadataInterface`, `PropertyMetadataInterface`, `ClassBasedInterface` and `PropertyMetadataContainerInterface`
+ * deprecated `GraphWalker` in favor of the new `ValidationVisitorInterface`
+ * deprecated `ExecutionContext::addViolationAtPath`
+ * deprecated `ExecutionContext::addViolationAtSubPath` in favor of `ExecutionContextInterface::addViolationAt`
+ * deprecated `ExecutionContext::getCurrentClass` in favor of `ExecutionContextInterface::getClassName`
+ * deprecated `ExecutionContext::getCurrentProperty` in favor of `ExecutionContextInterface::getPropertyName`
+ * deprecated `ExecutionContext::getCurrentValue` in favor of `ExecutionContextInterface::getValue`
+ * deprecated `ExecutionContext::getGraphWalker` in favor of `ExecutionContextInterface::validate` and `ExecutionContextInterface::validateValue`
+ * deprecated `ExecutionContext::getMetadataFactory` in favor of `ExecutionContextInterface::getMetadataFor`
+ * improved `ValidatorInterface::validateValue` to accept arrays of constraints
+ * changed `ValidatorInterface::getMetadataFactory` to return a `MetadataFactoryInterface` instead of a `ClassMetadataFactoryInterface`
+ * removed `ClassMetadataFactoryInterface` type hint from `ValidatorBuilderInterface::setMetadataFactory`.
+   As of Symfony 2.3, this method will be typed against `MetadataFactoryInterface` instead.
 
 2.1.0
 -----

ClassBasedInterface.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Validator;
+
+/**
+ * An object backed by a PHP class.
+ *
+ * @author Bernhard Schussek <[email protected]>
+ */
+interface ClassBasedInterface
+{
+    /**
+     * Returns the name of the backing PHP class.
+     *
+     * @return string The name of the backing class.
+     */
+    public function getClassName();
+}

ConstraintValidator.php

@@ -23,7 +23,7 @@
 abstract class ConstraintValidator implements ConstraintValidatorInterface
 {
     /**
-     * @var ExecutionContext
+     * @var ExecutionContextInterface
      */
     protected $context;
 
@@ -44,7 +44,7 @@ abstract class ConstraintValidator implements ConstraintValidatorInterface
     /**
      * {@inheritDoc}
      */
-    public function initialize(ExecutionContext $context)
+    public function initialize(ExecutionContextInterface $context)
     {
         $this->context = $context;
         $this->messageTemplate = '';

ConstraintValidatorInterface.php

@@ -21,9 +21,9 @@ interface ConstraintValidatorInterface
     /**
      * Initializes the constraint validator.
      *
-     * @param ExecutionContext $context The current validation context
+     * @param ExecutionContextInterface $context The current validation context
      */
-    public function initialize(ExecutionContext $context);
+    public function initialize(ExecutionContextInterface $context);
 
     /**
      * Checks if the passed value is valid.

ConstraintViolation.php

@@ -12,20 +12,64 @@
 namespace Symfony\Component\Validator;
 
 /**
- * Represents a single violation of a constraint.
+ * Default implementation of {@ConstraintViolationInterface}.
  *
- * @api
+ * @author Bernhard Schussek <[email protected]>
  */
-class ConstraintViolation
+class ConstraintViolation implements ConstraintViolationInterface
 {
-    protected $messageTemplate;
-    protected $messageParameters;
-    protected $messagePluralization;
-    protected $root;
-    protected $propertyPath;
-    protected $invalidValue;
-    protected $code;
+    /**
+     * @var string
+     */
+    private $messageTemplate;
+
+    /**
+     * @var array
+     */
+    private $messageParameters;
+
+    /**
+     * @var integer|null
+     */
+    private $messagePluralization;
+
+    /**
+     * @var mixed
+     */
+    private $root;
+
+    /**
+     * @var string
+     */
+    private $propertyPath;
+
+    /**
+     * @var mixed
+     */
+    private $invalidValue;
+
+    /**
+     * @var mixed
+     */
+    private $code;
 
+    /**
+     * Creates a new constraint violation.
+     *
+     * @param string       $messageTemplate       The raw violation message.
+     * @param array        $messageParameters     The parameters to substitute
+     *                                            in the raw message.
+     * @param mixed        $root                  The value originally passed
+     *                                            to the validator.
+     * @param string       $propertyPath          The property path from the
+     *                                            root value to the invalid
+     *                                            value.
+     * @param mixed        $invalidValue          The invalid value causing the
+     *                                            violation.
+     * @param integer|null $messagePluralization  The pluralization parameter.
+     * @param mixed        $code                  The error code of the
+     *                                            violation, if any.
+     */
     public function __construct($messageTemplate, array $messageParameters, $root, $propertyPath, $invalidValue, $messagePluralization = null, $code = null)
     {
         $this->messageTemplate = $messageTemplate;
@@ -38,7 +82,9 @@ public function __construct($messageTemplate, array $messageParameters, $root, $
     }
 
     /**
-     * @return string
+     * Converts the violation into a string for debugging purposes.
+     *
+     * @return string The violation as string.
      */
     public function __toString()
     {
@@ -58,39 +104,31 @@ public function __toString()
     }
 
     /**
-     * @return string
-     *
-     * @api
+     * {@inheritDoc}
      */
     public function getMessageTemplate()
     {
         return $this->messageTemplate;
     }
 
     /**
-     * @return array
-     *
-     * @api
+     * {@inheritDoc}
      */
     public function getMessageParameters()
     {
         return $this->messageParameters;
     }
 
     /**
-     * @return integer|null
+     * {@inheritDoc}
      */
     public function getMessagePluralization()
     {
         return $this->messagePluralization;
     }
 
     /**
-     * Returns the violation message.
-     *
-     * @return string
-     *
-     * @api
+     * {@inheritDoc}
      */
     public function getMessage()
     {
@@ -105,21 +143,33 @@ public function getMessage()
         return strtr($this->messageTemplate, $parameters);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getRoot()
     {
         return $this->root;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getPropertyPath()
     {
         return $this->propertyPath;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getInvalidValue()
     {
         return $this->invalidValue;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getCode()
     {
         return $this->code;

ConstraintViolationInterface.php

@@ -0,0 +1,136 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Validator;
+
+/**
+ * A violation of a constraint that happened during validation.
+ *
+ * For each constraint that fails during validation one or more violations are
+ * created. The violations store the violation message, the path to the failing
+ * element in the validation graph and the root element that was originally
+ * passed to the validator. For example, take the following graph:
+ *
+ * <pre>
+ * (Person)---(firstName: string)
+ *      \
+ *   (address: Address)---(street: string)
+ * </pre>
+ *
+ * If the <tt>Person</tt> object is validated and validation fails for the
+ * "firstName" property, the generated violation has the <tt>Person</tt>
+ * instance as root and the property path "firstName". If validation fails
+ * for the "street" property of the related <tt>Address</tt> instance, the root
+ * element is still the person, but the property path is "address.street".
+ *
+ * @author Bernhard Schussek <[email protected]>
+ *
+ * @api
+ */
+interface ConstraintViolationInterface
+{
+    /**
+     * Returns the violation message.
+     *
+     * @return string The violation message.
+     *
+     * @api
+     */
+    public function getMessage();
+
+    /**
+     * Returns the raw violation message.
+     *
+     * The raw violation message contains placeholders for the parameters
+     * returned by {@link getMessageParameters}. Typically you'll pass the
+     * message template and parameters to a translation engine.
+     *
+     * @return string The raw violation message.
+     *
+     * @api
+     */
+    public function getMessageTemplate();
+
+    /**
+     * Returns the parameters to be inserted into the raw violation message.
+     *
+     * @return array A possibly empty list of parameters indexed by the names
+     *               that appear in the message template.
+     *
+     * @see getMessageTemplate
+     *
+     * @api
+     */
+    public function getMessageParameters();
+
+    /**
+     * Returns a number for pluralizing the violation message.
+     *
+     * For example, the message template could have different translation based
+     * on a parameter "choices":
+     *
+     * <ul>
+     * <li>Please select exactly one entry. (choices=1)</li>
+     * <li>Please select two entries. (choices=2)</li>
+     * </ul>
+     *
+     * This method returns the value of the parameter for choosing the right
+     * pluralization form (in this case "choices").
+     *
+     * @return integer|null The number to use to pluralize of the message.
+     */
+    public function getMessagePluralization();
+
+    /**
+     * Returns the root element of the validation.
+     *
+     * @return mixed The value that was passed originally to the validator when
+     *               the validation was started. Because the validator traverses
+     *               the object graph, the value at which the violation occurs
+     *               is not necessarily the value that was originally validated.
+     *
+     * @api
+     */
+    public function getRoot();
+
+    /**
+     * Returns the property path from the root element to the violation.
+     *
+     * @return string The property path indicates how the validator reached
+     *                the invalid value from the root element. If the root
+     *                element is a <tt>Person</tt> instance with a property
+     *                "address" that contains an <tt>Address</tt> instance
+     *                with an invalid property "street", the generated property
+     *                path is "address.street". Property access is denoted by
+     *                dots, while array access is denoted by square brackets,
+     *                for example "addresses[1].street".
+     *
+     * @api
+     */
+    public function getPropertyPath();
+
+    /**
+     * Returns the value that caused the violation.
+     *
+     * @return mixed The invalid value that caused the validated constraint to
+     *               fail.
+     *
+     * @api
+     */
+    public function getInvalidValue();
+
+    /**
+     * Returns a machine-digestible error code for the violation.
+     *
+     * @return mixed The error code.
+     */
+    public function getCode();
+}