feature #34456 [Validator] Add a constraint to sequentially validate …

…a set of constraints (ogizanagi)

This PR was merged into the 5.1-dev branch.

Discussion
----------

[Validator] Add a constraint to sequentially validate a set of constraints

| Q             | A
| ------------- | ---
| Branch?       | master <!-- see below -->
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | no <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tickets       | N/A <!-- prefix each issue number with "Fix #", if any -->
| License       | MIT
| Doc PR        | Todo

Follows #20017 (comment) given some feedbacks about the suggested feature.

```php
/**
 * @var string
 *
 * @Assert\Sequentially({
 *     @Assert\Type("string"),
 *     @Assert\Length(min="4"),
 *     @Assert\Regex("[a-z]"),
 *     @SomeCustomConstraintWithHeavyExternalCalls(),
 * })
 */
public $foo;
```

This new `Sequentially` constraint solves - with less power but better DX - some of the use-cases of the `GroupSequence` feature, allowing to interrupt the validation of some constraints if a previous one in the list failed before. Constraints are validated in given order, and the first violation raised will prevent other constraint validators to be executed.
It can either prevent unexpected type exceptions thrown by further constraints or heavy & unnecessary calls to a database or external services if the value to validate already doesn't match some of the basic requirements.

Commits
-------

dfd9038 [Validator] Add a constraint to sequentially validate a set of constraints

src/Symfony/Component/Validator/CHANGELOG.md

@@ -7,6 +7,7 @@ CHANGELOG
  * added the `Hostname` constraint and validator
  * added option `alpha3` to `Country` constraint
  * allow to define a reusable set of constraints by extending the `Compound` constraint
+ * added `Sequentially` constraint, to sequentially validate a set of constraints (any violation raised will prevent further validation of the nested constraints)
 
 5.0.0
 -----

src/Symfony/Component/Validator/Constraints/Sequentially.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Validator\Constraints;
+
+/**
+ * Use this constraint to sequentially validate nested constraints.
+ * Validation for the nested constraints collection will stop at first violation.
+ *
+ * @Annotation
+ * @Target({"PROPERTY", "METHOD", "ANNOTATION"})
+ *
+ * @author Maxime Steinhausser <maxime.steinhausser@gmail.com>
+ */
+class Sequentially extends Composite
+{
+    public $constraints = [];
+
+    public function getDefaultOption()
+    {
+        return 'constraints';
+    }
+
+    public function getRequiredOptions()
+    {
+        return ['constraints'];
+    }
+
+    protected function getCompositeOption()
+    {
+        return 'constraints';
+    }
+}

src/Symfony/Component/Validator/Constraints/SequentiallyValidator.php

@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Validator\Constraints;
+
+use Symfony\Component\Validator\Constraint;
+use Symfony\Component\Validator\ConstraintValidator;
+use Symfony\Component\Validator\Exception\UnexpectedTypeException;
+
+/**
+ * @author Maxime Steinhausser <maxime.steinhausser@gmail.com>
+ */
+class SequentiallyValidator extends ConstraintValidator
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function validate($value, Constraint $constraint)
+    {
+        if (!$constraint instanceof Sequentially) {
+            throw new UnexpectedTypeException($constraint, Sequentially::class);
+        }
+
+        $context = $this->context;
+
+        $validator = $context->getValidator()->inContext($context);
+
+        $originalCount = $validator->getViolations()->count();
+
+        foreach ($constraint->constraints as $c) {
+            if ($originalCount !== $validator->validate($value, $c)->getViolations()->count()) {
+                break;
+            }
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Validator\Tests\Constraints;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Validator\Constraints\Sequentially;
+use Symfony\Component\Validator\Constraints\Valid;
+use Symfony\Component\Validator\Exception\ConstraintDefinitionException;
+
+class SequentiallyTest extends TestCase
+{
+    public function testRejectNonConstraints()
+    {
+        $this->expectException(ConstraintDefinitionException::class);
+        $this->expectExceptionMessage('The value foo is not an instance of Constraint in constraint Symfony\Component\Validator\Constraints\Sequentially');
+        new Sequentially([
+            'foo',
+        ]);
+    }
+
+    public function testRejectValidConstraint()
+    {
+        $this->expectException(ConstraintDefinitionException::class);
+        $this->expectExceptionMessage('The constraint Valid cannot be nested inside constraint Symfony\Component\Validator\Constraints\Sequentially');
+        new Sequentially([
+            new Valid(),
+        ]);
+    }
+}

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

@@ -0,0 +1,87 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Validator\Tests\Constraints;
+
+use Symfony\Component\Validator\Constraints\NotEqualTo;
+use Symfony\Component\Validator\Constraints\Range;
+use Symfony\Component\Validator\Constraints\Regex;
+use Symfony\Component\Validator\Constraints\Sequentially;
+use Symfony\Component\Validator\Constraints\SequentiallyValidator;
+use Symfony\Component\Validator\Constraints\Type;
+use Symfony\Component\Validator\ConstraintViolation;
+use Symfony\Component\Validator\Test\ConstraintValidatorTestCase;
+
+class SequentiallyValidatorTest extends ConstraintValidatorTestCase
+{
+    protected function createValidator()
+    {
+        return new SequentiallyValidator();
+    }
+
+    public function testWalkThroughConstraints()
+    {
+        $constraints = [
+            new Type('number'),
+            new Range(['min' => 4]),
+        ];
+
+        $value = 6;
+
+        $contextualValidator = $this->context->getValidator()->inContext($this->context);
+        $contextualValidator->expects($this->any())->method('getViolations')->willReturn($this->context->getViolations());
+        $contextualValidator->expects($this->exactly(2))
+            ->method('validate')
+            ->withConsecutive(
+                [$value, $constraints[0]],
+                [$value, $constraints[1]]
+            )
+            ->willReturn($contextualValidator);
+
+        $this->validator->validate($value, new Sequentially($constraints));
+
+        $this->assertNoViolation();
+    }
+
+    public function testStopsAtFirstConstraintWithViolations()
+    {
+        $constraints = [
+            new Type('string'),
+            new Regex(['pattern' => '[a-z]']),
+            new NotEqualTo('Foo'),
+        ];
+
+        $value = 'Foo';
+
+        $contextualValidator = $this->context->getValidator()->inContext($this->context);
+        $contextualValidator->expects($this->any())->method('getViolations')->willReturn($this->context->getViolations());
+        $contextualValidator->expects($this->exactly(2))
+            ->method('validate')
+            ->withConsecutive(
+                [$value, $constraints[0]],
+                [$value, $constraints[1]]
+            )
+            ->will($this->onConsecutiveCalls(
+                // Noop, just return the validator:
+                $this->returnValue($contextualValidator),
+                // Add violation on second call:
+                $this->returnCallback(function () use ($contextualValidator) {
+                    $this->context->getViolations()->add($violation = new ConstraintViolation('regex error', null, [], null, '', null, null, 'regex'));
+
+                    return $contextualValidator;
+                }
+            )));
+
+        $this->validator->validate($value, new Sequentially($constraints));
+
+        $this->assertCount(1, $this->context->getViolations());
+    }
+}