Enable validating inputs without throwing exceptions

Currently, the only way to handle when a validation fails is by
`assert()`, which either throws an exception or doesn't. That means that
every time a user wants to handle the results, they must use try-catch
blocks, which may add some overhead.

This commit introduces the `ResultQuery` class that wraps a `Result`
object, providing an alternative to exception-based validation. This
allows users to handle results directly without try-catch blocks.

I’m taking a risky move here using the old method `validate()`, but I
can’t think of a better name for this method.

Author: henriquemoody

library/Exceptions/ValidationException.php

@@ -18,8 +18,8 @@
 final class ValidationException extends InvalidArgumentException implements Exception
 {
     /**
-     * @param array<string, mixed> $messages
-     * @param array<string>        $ignoredBacktracePaths
+     * @param array<string|int, mixed> $messages
+     * @param array<string>            $ignoredBacktracePaths
      */
     public function __construct(
         string $message,
@@ -37,7 +37,7 @@ public function getFullMessage(): string
         return $this->fullMessage;
     }
 
-    /** @return array<string, mixed> */
+    /** @return array<string|int, mixed> */
     public function getMessages(): array
     {
         return $this->messages;

library/Message/ArrayFormatter.php

@@ -14,9 +14,9 @@
 interface ArrayFormatter
 {
     /**
-     * @param array<string, mixed> $templates
+     * @param array<string|int, mixed> $templates
      *
-     * @return array<string, mixed>
+     * @return array<string|int, mixed>
      */
     public function format(Result $result, Renderer $renderer, array $templates): array;
 }

library/Message/StringFormatter.php

@@ -13,6 +13,6 @@
 
 interface StringFormatter
 {
-    /** @param array<string, mixed> $templates */
+    /** @param array<string|int, mixed> $templates */
     public function format(Result $result, Renderer $renderer, array $templates): string;
 }

library/ResultQuery.php

@@ -0,0 +1,133 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+namespace Respect\Validation;
+
+use Respect\Validation\Message\ArrayFormatter;
+use Respect\Validation\Message\Renderer;
+use Respect\Validation\Message\StringFormatter;
+use Stringable;
+
+use function array_shift;
+use function explode;
+use function implode;
+use function is_string;
+
+final readonly class ResultQuery implements Stringable
+{
+    /** @param array<string|int, mixed> $templates */
+    public function __construct(
+        private Result $result,
+        private Renderer $renderer,
+        private StringFormatter $messageFormatter,
+        private StringFormatter $fullMessageFormatter,
+        private ArrayFormatter $messagesFormatter,
+        private array $templates,
+    ) {
+    }
+
+    public function findById(string $id): self|null
+    {
+        if ($this->result->id->value === $id) {
+            return $this;
+        }
+
+        foreach ($this->result->children as $child) {
+            $resultQuery = clone ($this, ['result' => $child]);
+            if ($child->id->value === $id) {
+                return $resultQuery;
+            }
+
+            return $resultQuery->findById($id);
+        }
+
+        return null;
+    }
+
+    public function findByName(string $name): self|null
+    {
+        if ($this->result->name?->value === $name) {
+            return $this;
+        }
+
+        foreach ($this->result->children as $child) {
+            $resultQuery = clone ($this, ['result' => $child]);
+            if ($child->name?->value === $name) {
+                return $resultQuery;
+            }
+
+            return $resultQuery->findByName($name);
+        }
+
+        return null;
+    }
+
+    public function findByPath(string|int $path): self|null
+    {
+        if ($this->result->path?->value === $path) {
+            return $this;
+        }
+
+        $paths = is_string($path) ? explode('.', $path) : [$path];
+        $currentPath = array_shift($paths);
+
+        foreach ($this->result->children as $child) {
+            if ($child->path?->value !== $currentPath) {
+                continue;
+            }
+
+            $resultQuery = clone ($this, ['result' => $child]);
+            if ($paths === []) {
+                return $resultQuery;
+            }
+
+            return $resultQuery->findByPath(is_string($path) ? implode('.', $paths) : $path);
+        }
+
+        return null;
+    }
+
+    public function isValid(): bool
+    {
+        return $this->result->hasPassed;
+    }
+
+    public function toMessage(): string
+    {
+        if ($this->result->hasPassed) {
+            return '';
+        }
+
+        return $this->messageFormatter->format($this->result, $this->renderer, $this->templates);
+    }
+
+    public function toFullMessage(): string
+    {
+        if ($this->result->hasPassed) {
+            return '';
+        }
+
+        return $this->fullMessageFormatter->format($this->result, $this->renderer, $this->templates);
+    }
+
+    /** @return array<string|int, mixed> */
+    public function toArrayMessages(): array
+    {
+        if ($this->result->hasPassed) {
+            return [];
+        }
+
+        return $this->messagesFormatter->format($this->result, $this->renderer, $this->templates);
+    }
+
+    public function __toString(): string
+    {
+        return $this->toMessage();
+    }
+}

library/Validator.php

@@ -60,12 +60,18 @@ public function evaluate(mixed $input): Result
         return $this->getRule()->evaluate($input);
     }
 
+    /** @param array<string|int, mixed>|string|null $template */
+    public function validate(mixed $input, array|string|null $template = null): ResultQuery
+    {
+        return $this->toResultQuery($this->evaluate($input), $template);
+    }
+
     public function isValid(mixed $input): bool
     {
         return $this->evaluate($input)->hasPassed;
     }
 
-    /** @param array<string, mixed>|callable(ValidationException): Throwable|string|Throwable|null $template */
+    /** @param array<string|int, mixed>|callable(ValidationException): Throwable|string|Throwable|null $template */
     public function assert(mixed $input, array|string|Throwable|callable|null $template = null): void
     {
         $result = $this->evaluate($input);
@@ -77,29 +83,20 @@ public function assert(mixed $input, array|string|Throwable|callable|null $templ
             throw $template;
         }
 
-        $failedResult = $this->resultFilter->filter($result);
-
-        $templates = $this->templates;
-        if (is_array($template)) {
-            $templates = $template;
-        } elseif (is_string($template)) {
-            $failedResult = $failedResult->withTemplate($template);
-        } elseif ($this->getTemplate() != null) {
-            $failedResult = $failedResult->withTemplate($this->getTemplate());
-        }
+        $resultQuery = $this->toResultQuery($result, is_callable($template) ? null : $template);
 
         $exception = new ValidationException(
-            $this->mainMessageFormatter->format($failedResult, $this->renderer, $templates),
-            $this->fullMessageFormatter->format($failedResult, $this->renderer, $templates),
-            $this->messagesFormatter->format($failedResult, $this->renderer, $templates),
+            $resultQuery->toMessage(),
+            $resultQuery->toFullMessage(),
+            $resultQuery->toArrayMessages(),
             $this->ignoredBacktracePaths,
         );
 
-        if (!is_callable($template)) {
-            throw $exception;
+        if (is_callable($template)) {
+            throw $template($exception);
         }
 
-        throw $template($exception);
+        throw $exception;
     }
 
     /** @param array<string|int, mixed> $templates */
@@ -161,6 +158,25 @@ public function setTemplate(string $template): static
         return $this;
     }
 
+    /** @param array<string|int, mixed>|string|null $template */
+    private function toResultQuery(Result $result, array|string|null $template): ResultQuery
+    {
+        if (is_string($template)) {
+            $result = $result->withTemplate($template);
+        } elseif ($this->getTemplate() != null) {
+            $result = $result->withTemplate($this->getTemplate());
+        }
+
+        return new ResultQuery(
+            $this->resultFilter->filter($result),
+            $this->renderer,
+            $this->mainMessageFormatter,
+            $this->fullMessageFormatter,
+            $this->messagesFormatter,
+            is_array($template) ? $template : $this->templates,
+        );
+    }
+
     /** @param mixed[] $arguments */
     public static function __callStatic(string $ruleName, array $arguments): self
     {

tests/library/Message/TestingArrayFormatter.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Validation\Test\Message;
+
+use Respect\Validation\Message\ArrayFormatter;
+use Respect\Validation\Message\Renderer;
+use Respect\Validation\Result;
+
+final class TestingArrayFormatter implements ArrayFormatter
+{
+    /**
+     * @param array<string|int, mixed> $templates
+     *
+     * @return array<string|int, mixed>
+     */
+    public function format(Result $result, Renderer $renderer, array $templates): array
+    {
+        return [$result->id->value => $renderer->render($result, $templates)];
+    }
+}

tests/library/Message/TestingStringFormatter.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Validation\Test\Message;
+
+use Respect\Validation\Message\Renderer;
+use Respect\Validation\Message\StringFormatter;
+use Respect\Validation\Result;
+
+final class TestingStringFormatter implements StringFormatter
+{
+    public function __construct(
+        private readonly string $prefix = '',
+    ) {
+    }
+
+    /** @param array<string|int, mixed> $templates */
+    public function format(Result $result, Renderer $renderer, array $templates): string
+    {
+        return $this->prefix . $renderer->render($result, $templates);
+    }
+}