feature #12052 [Validator] Made it possible to store the cause of a c…

…onstraint violation (webmozart)

This PR was merged into the 2.6-dev branch.

Discussion
----------

[Validator] Made it possible to store the cause of a constraint violation

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | yes
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | TODO

This change makes it possible to store the cause of a violation (e.g. an exception). This way it is possible to follow the trace of violations caused by exceptions up to their root.

```php
try {
    // ...
} catch (Exception $e) {
    $this->context->buildViolation('Error!')
        ->setCause($e)
        ->addViolation();
}
```

This is one step to solve #5607. See #12054.

Commits
-------

499eeb4 [Validator] Made it possible to store the cause of a constraint violation

src/Symfony/Component/Validator/CHANGELOG.md

@@ -14,6 +14,7 @@ CHANGELOG
  * deprecated `ClassMetadata::addMemberMetadata()`
  * [BC BREAK] added `Mapping\MetadataInterface::getConstraints()`
  * added generic "payload" option to all constraints for attaching domain-specific data
+ * [BC BREAK] added `ConstraintViolationBuilderInterface::setCause()`
 
 2.5.0
 -----

src/Symfony/Component/Validator/ConstraintViolation.php

@@ -63,6 +63,11 @@ class ConstraintViolation implements ConstraintViolationInterface
      */
     private $code;
 
+    /**
+     * @var mixed
+     */
+    private $cause;
+
     /**
      * Creates a new constraint violation.
      *
@@ -79,10 +84,11 @@ class ConstraintViolation implements ConstraintViolationInterface
      * @param int|null        $plural          The number for determining the plural
      *                                         form when translating the message
      * @param mixed           $code            The error code of the violation
-     * @param Constraint|null $constraint      The constraint that caused the
-     *                                         violation
+     * @param Constraint|null $constraint      The constraint whose validation
+     *                                         caused the violation
+     * @param mixed           $cause           The cause of the violation
      */
-    public function __construct($message, $messageTemplate, array $parameters, $root, $propertyPath, $invalidValue, $plural = null, $code = null, Constraint $constraint = null)
+    public function __construct($message, $messageTemplate, array $parameters, $root, $propertyPath, $invalidValue, $plural = null, $code = null, Constraint $constraint = null, $cause = null)
     {
         $this->message = $message;
         $this->messageTemplate = $messageTemplate;
@@ -93,6 +99,7 @@ public function __construct($message, $messageTemplate, array $parameters, $root
         $this->invalidValue = $invalidValue;
         $this->constraint = $constraint;
         $this->code = $code;
+        $this->cause = $cause;
     }
 
     /**
@@ -197,7 +204,7 @@ public function getInvalidValue()
     }
 
     /**
-     * Returns the constraint that caused the violation.
+     * Returns the constraint whose validation caused the violation.
      *
      * @return Constraint|null The constraint or null if it is not known
      */
@@ -206,6 +213,16 @@ public function getConstraint()
         return $this->constraint;
     }
 
+    /**
+     * Returns the cause of the violation.
+     *
+     * @return mixed
+     */
+    public function getCause()
+    {
+        return $this->cause;
+    }
+
     /**
      * {@inheritdoc}
      */

src/Symfony/Component/Validator/Tests/Constraints/AbstractConstraintValidatorTest.php

@@ -428,6 +428,7 @@ class ConstraintViolationAssertion
     private $plural;
     private $code;
     private $constraint;
+    private $cause;
 
     public function __construct(LegacyExecutionContextInterface $context, $message, Constraint $constraint = null, array $assertions = array())
     {
@@ -486,6 +487,13 @@ public function setCode($code)
         return $this;
     }
 
+    public function setCause($cause)
+    {
+        $this->cause = $cause;
+
+        return $this;
+    }
+
     public function buildNextViolation($message)
     {
         $assertions = $this->assertions;
@@ -525,7 +533,8 @@ private function getViolation()
             $this->invalidValue,
             $this->plural,
             $this->code,
-            $this->constraint
+            $this->constraint,
+            $this->cause
         );
     }
 }

src/Symfony/Component/Validator/Violation/ConstraintViolationBuilder.php

@@ -83,6 +83,11 @@ class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
      */
     private $code;
 
+    /**
+     * @var mixed
+     */
+    private $cause;
+
     public function __construct(ConstraintViolationList $violations, Constraint $constraint, $message, array $parameters, $root, $propertyPath, $invalidValue, TranslatorInterface $translator, $translationDomain = null)
     {
         $this->violations = $violations;
@@ -166,6 +171,16 @@ public function setCode($code)
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function setCause($cause)
+    {
+        $this->cause = $cause;
+
+        return $this;
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -203,7 +218,8 @@ public function addViolation()
             $this->invalidValue,
             $this->plural,
             $this->code,
-            $this->constraint
+            $this->constraint,
+            $this->cause
         ));
     }
 }

src/Symfony/Component/Validator/Violation/ConstraintViolationBuilderInterface.php

@@ -101,6 +101,15 @@ public function setPlural($number);
      */
     public function setCode($code);
 
+    /**
+     * Sets the cause of the violation.
+     *
+     * @param mixed $cause The cause of the violation
+     *
+     * @return ConstraintViolationBuilderInterface This builder
+     */
+    public function setCause($cause);
+
     /**
      * Adds the violation to the current execution context.
      */

src/Symfony/Component/Validator/Violation/LegacyConstraintViolationBuilder.php

@@ -11,12 +11,7 @@
 
 namespace Symfony\Component\Validator\Violation;
 
-use Symfony\Component\Translation\TranslatorInterface;
-use Symfony\Component\Validator\Constraint;
-use Symfony\Component\Validator\ConstraintViolation;
-use Symfony\Component\Validator\ConstraintViolationList;
 use Symfony\Component\Validator\ExecutionContextInterface;
-use Symfony\Component\Validator\Util\PropertyPath;
 
 /**
  * Backwards-compatible implementation of {@link ConstraintViolationBuilderInterface}.
@@ -149,6 +144,16 @@ public function setCode($code)
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function setCause($cause)
+    {
+        // do nothing - we can't save the cause through the old API
+
+        return $this;
+    }
+
     /**
      * {@inheritdoc}
      */