Merge branch 'release/5.0.0-rc.3'

lindyhopchris · lindyhopchris · commit cad45c974337 · 2025-10-14T13:57:10.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+## [5.0.0-rc.3] - 2025-10-14
+
+### Added
+
+- **BREAKING** Command and query validators can now return early on the first validation failure, by marking the
+  validator with the `stopOnFirstFailure()` method. This is technically a breaking change as the method was added to the
+  validator interface; however, if you are using the `Validator` class provided by this package, it now implements this
+  method.
+- Middleware that extend `ValidateCommand` and `ValidateQuery` can mark themselves as stopping on the first failure by
+  implementing the `Bail` interface, or overloading the `stopOnFirstFailure()` method to return `true`.
+
 ## [5.0.0-rc.2] - 2025-10-14
 
 ### Added
diff --git a/src/Application/Bus/Middleware/ValidateCommand.php b/src/Application/Bus/Middleware/ValidateCommand.php
@@ -13,6 +13,7 @@
 namespace CloudCreativity\Modules\Application\Bus\Middleware;
 
 use Closure;
+use CloudCreativity\Modules\Contracts\Application\Bus\Bail;
 use CloudCreativity\Modules\Contracts\Application\Bus\CommandMiddleware;
 use CloudCreativity\Modules\Contracts\Application\Bus\Validator;
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
@@ -36,6 +37,7 @@ public function __invoke(Command $command, Closure $next): IResult
     {
         $errors = $this->validator
             ->using($this->rules())
+            ->stopOnFirstFailure($this->stopOnFirstFailure($command))
             ->validate($command);
 
         if ($errors->isNotEmpty()) {
@@ -44,4 +46,9 @@ public function __invoke(Command $command, Closure $next): IResult
 
         return $next($command);
     }
+
+    protected function stopOnFirstFailure(Command $command): bool
+    {
+        return $this instanceof Bail;
+    }
 }
diff --git a/src/Application/Bus/Middleware/ValidateQuery.php b/src/Application/Bus/Middleware/ValidateQuery.php
@@ -13,6 +13,7 @@
 namespace CloudCreativity\Modules\Application\Bus\Middleware;
 
 use Closure;
+use CloudCreativity\Modules\Contracts\Application\Bus\Bail;
 use CloudCreativity\Modules\Contracts\Application\Bus\QueryMiddleware;
 use CloudCreativity\Modules\Contracts\Application\Bus\Validator;
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Query;
@@ -36,6 +37,7 @@ public function __invoke(Query $query, Closure $next): IResult
     {
         $errors = $this->validator
             ->using($this->rules())
+            ->stopOnFirstFailure($this->stopOnFirstFailure($query))
             ->validate($query);
 
         if ($errors->isNotEmpty()) {
@@ -44,4 +46,9 @@ public function __invoke(Query $query, Closure $next): IResult
 
         return $next($query);
     }
+
+    protected function stopOnFirstFailure(Query $query): bool
+    {
+        return $this instanceof Bail;
+    }
 }
diff --git a/src/Application/Bus/ValidationProcessor.php b/src/Application/Bus/ValidationProcessor.php
@@ -0,0 +1,49 @@
+<?php
+
+/*
+ * Copyright 2025 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Application\Bus;
+
+use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
+use CloudCreativity\Modules\Contracts\Toolkit\Messages\Query;
+use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\Processor;
+use CloudCreativity\Modules\Toolkit\Result\ListOfErrors;
+
+final readonly class ValidationProcessor implements Processor
+{
+    public function __construct(private bool $stopOnFirstFailure = false)
+    {
+    }
+
+    /**
+     * @param (callable(Command|Query): ?ListOfErrors) ...$stages
+     */
+    public function process(mixed $payload, callable ...$stages): ListOfErrors
+    {
+        assert($payload instanceof Command || $payload instanceof Query);
+
+        $errors = new ListOfErrors();
+
+        foreach ($stages as $stage) {
+            $result = $stage($payload);
+
+            if ($result) {
+                $errors = $errors->merge($result);
+            }
+
+            if ($this->stopOnFirstFailure && $errors->isNotEmpty()) {
+                return $errors;
+            }
+        }
+
+        return $errors;
+    }
+}
diff --git a/src/Application/Bus/Validator.php b/src/Application/Bus/Validator.php
@@ -18,7 +18,6 @@
 use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\PipeContainer;
 use CloudCreativity\Modules\Contracts\Toolkit\Pipeline\Pipeline;
 use CloudCreativity\Modules\Contracts\Toolkit\Result\ListOfErrors as IListOfErrors;
-use CloudCreativity\Modules\Toolkit\Pipeline\AccumulationProcessor;
 use CloudCreativity\Modules\Toolkit\Pipeline\PipelineBuilder;
 use CloudCreativity\Modules\Toolkit\Result\ListOfErrors;
 
@@ -29,21 +28,26 @@ final class Validator implements IValidator
      */
     private iterable $using = [];
 
+    private bool $stopOnFirstFailure = false;
+
     public function __construct(private readonly ?PipeContainer $rules = null)
     {
     }
 
-    /**
-     * @param iterable<callable|string> $rules
-     * @return $this
-     */
     public function using(iterable $rules): static
     {
         $this->using = $rules;
 
         return $this;
     }
 
+    public function stopOnFirstFailure(bool $stop = true): static
+    {
+        $this->stopOnFirstFailure = $stop;
+
+        return $this;
+    }
+
     public function validate(Command|Query $message): IListOfErrors
     {
         $errors = $this
@@ -59,16 +63,6 @@ private function getPipeline(): Pipeline
     {
         return PipelineBuilder::make($this->rules)
             ->through($this->using)
-            ->build($this->processor());
-    }
-
-    private function processor(): AccumulationProcessor
-    {
-        return new AccumulationProcessor(
-            static function (?IListOfErrors $carry, ?IListOfErrors $errors): IListOfErrors {
-                $errors ??= new ListOfErrors();
-                return $carry ? $carry->merge($errors) : $errors;
-            },
-        );
+            ->build(new ValidationProcessor($this->stopOnFirstFailure));
     }
 }
diff --git a/src/Contracts/Application/Bus/Bail.php b/src/Contracts/Application/Bus/Bail.php
@@ -0,0 +1,17 @@
+<?php
+
+/*
+ * Copyright 2025 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Modules\Contracts\Application\Bus;
+
+interface Bail
+{
+}
diff --git a/src/Contracts/Application/Bus/Validator.php b/src/Contracts/Application/Bus/Validator.php
@@ -26,6 +26,13 @@ interface Validator
      */
     public function using(iterable $rules): static;
 
+    /**
+     * Stop validating as soon as the first rule fails.
+     *
+     * @return $this
+     */
+    public function stopOnFirstFailure(bool $stop = true): static;
+
     /**
      * Validate the provided message.
      */
diff --git a/tests/Unit/Application/Bus/Middleware/ValidateCommandTest.php b/tests/Unit/Application/Bus/Middleware/ValidateCommandTest.php
@@ -13,6 +13,7 @@
 namespace CloudCreativity\Modules\Tests\Unit\Application\Bus\Middleware;
 
 use CloudCreativity\Modules\Application\Bus\Middleware\ValidateCommand;
+use CloudCreativity\Modules\Contracts\Application\Bus\Bail;
 use CloudCreativity\Modules\Contracts\Application\Bus\Validator;
 use CloudCreativity\Modules\Contracts\Toolkit\Messages\Command;
 use CloudCreativity\Modules\Contracts\Toolkit\Result\Result;
@@ -62,6 +63,11 @@ public function testItSucceeds(): void
             }))
             ->willReturnSelf();
 
+        $this->validator
+            ->expects($this->once())
+            ->method('stopOnFirstFailure')
+            ->willReturnSelf();
+
         $this->validator
             ->expects($this->once())
             ->method('validate')
@@ -85,9 +91,55 @@ public function testItSucceeds(): void
     public function testItFails(): void
     {
         $this->validator
+            ->expects($this->once())
             ->method('using')
             ->willReturnSelf();
 
+        $this->validator
+            ->expects($this->once())
+            ->method('stopOnFirstFailure')
+            ->with(false)
+            ->willReturnSelf();
+
+        $this->validator
+            ->expects($this->once())
+            ->method('validate')
+            ->with($command = $this->createMock(Command::class))
+            ->willReturn($errors = new ListOfErrors(new Error(null, 'Something went wrong.')));
+
+        $next = function () {
+            throw new \LogicException('Not expecting next closure to be called.');
+        };
+
+        $result = ($this->middleware)($command, $next);
+
+        $this->assertTrue($result->didFail());
+        $this->assertSame($errors, $result->errors());
+    }
+
+    public function testItStopsOnFirstFailureViaBail(): void
+    {
+        $this->middleware = new class ($this->validator) extends ValidateCommand implements Bail {
+            /**
+             * @return iterable<string>
+             */
+            protected function rules(): iterable
+            {
+                return ['foo', 'bar'];
+            }
+        };
+
+        $this->validator
+            ->expects($this->once())
+            ->method('using')
+            ->willReturnSelf();
+
+        $this->validator
+            ->expects($this->once())
+            ->method('stopOnFirstFailure')
+            ->with(true)
+            ->willReturnSelf();
+
         $this->validator
             ->expects($this->once())
             ->method('validate')
@@ -103,4 +155,55 @@ public function testItFails(): void
         $this->assertTrue($result->didFail());
         $this->assertSame($errors, $result->errors());
     }
+
+    public function testItStopsOnFirstFailure(): void
+    {
+        $command = $this->createMock(Command::class);
+
+        $this->middleware = new class ($command, $this->validator) extends ValidateCommand {
+            public function __construct(private Command $command, Validator $validator)
+            {
+                parent::__construct($validator);
+            }
+
+            /**
+             * @return iterable<string>
+             */
+            protected function rules(): iterable
+            {
+                return ['foo', 'bar'];
+            }
+
+            protected function stopOnFirstFailure(Command $command): bool
+            {
+                return $this->command === $command;
+            }
+        };
+
+        $this->validator
+            ->expects($this->once())
+            ->method('using')
+            ->willReturnSelf();
+
+        $this->validator
+            ->expects($this->once())
+            ->method('stopOnFirstFailure')
+            ->with(true)
+            ->willReturnSelf();
+
+        $this->validator
+            ->expects($this->once())
+            ->method('validate')
+            ->with($command)
+            ->willReturn($errors = new ListOfErrors(new Error(null, 'Something went wrong.')));
+
+        $next = function () {
+            throw new \LogicException('Not expecting next closure to be called.');
+        };
+
+        $result = ($this->middleware)($command, $next);
+
+        $this->assertTrue($result->didFail());
+        $this->assertSame($errors, $result->errors());
+    }
 }
diff --git a/tests/Unit/Application/Bus/Middleware/ValidateQueryTest.php b/tests/Unit/Application/Bus/Middleware/ValidateQueryTest.php
diff --git a/tests/Unit/Application/Bus/ValidatorTest.php b/tests/Unit/Application/Bus/ValidatorTest.php
