Initial work on stateless validation [RFC]

src/BaseInputFilter.php

@@ -22,6 +22,7 @@
 use function is_int;
 use function is_iterable;
 use function is_string;
+use function iterator_to_array;
 use function sprintf;
 
 /**
@@ -218,6 +219,37 @@ public function isValid(array|null $context = null): bool
         return $this->validateInputs($inputs, $this->data, $context);
     }
 
+    public function validate(iterable|null $data, array|null $context = null): InputFilterValidationResult
+    {
+        $data      = iterator_to_array($data ?? []);
+        $context ??= $data;
+        $inputs    = $this->validationGroup ?? array_keys($this->inputs);
+        $results   = [];
+        foreach ($inputs as $name) {
+            $input = $this->inputs[$name];
+            /** @psalm-var mixed $value */
+            $value = $data[$name] ?? null;
+
+            if ($input instanceof InputFilterInterface) {
+                $value = is_iterable($value) ? iterator_to_array($value) : [];
+
+                $result = $input->validate($value, $context);
+                assert($result instanceof InputFilterValidationResult);
+                $results[$name] = $result;
+
+                continue;
+            }
+
+            $result         = $input->validate($value, $context);
+            $results[$name] = $result;
+            if (! $result->valid() && $input->breakOnFailure()) {
+                break;
+            }
+        }
+
+        return new InputFilterValidationResult($results);
+    }
+
     /**
      * Validate a set of inputs against the current data
      *

src/Input.php

@@ -12,6 +12,7 @@
 use Laminas\Validator\ValidatorChain;
 use Laminas\Validator\ValidatorChainInterface;
 
+use function array_merge;
 use function assert;
 use function class_exists;
 use function get_debug_type;
@@ -277,6 +278,62 @@ public function merge(InputInterface $input): static
         return $this;
     }
 
+    public function validate(mixed $value, array $context): InputValidationResult
+    {
+        $isEmpty = $value === '' || $value === null || $value === [];
+        /** @psalm-var mixed $resolvedValue */
+        $resolvedValue = $isEmpty && $this->hasFallback ? $this->fallbackValue : $value;
+        /**
+         * Behaviour Change: The fallback value is filtered where previously it was returned verbatim
+         *
+         * @psalm-var mixed $filteredValue
+         */
+        $filteredValue = $this->filterChain->filter($resolvedValue);
+
+        if (
+            // We have a valid result when a value is empty, but a fallback is present
+            ($isEmpty && $this->hasFallback)
+            ||
+            // Empty values are valid when they are not required and validation should not continue for empty values
+            ($isEmpty && ! $this->required && ! $this->continueIfEmpty)
+            ||
+            // Empty is valid when allowEmpty is true and continue if empty is false
+            ($isEmpty && $this->allowEmpty && ! $this->continueIfEmpty)
+        ) {
+            return InputValidationResult::pass($this->name, $value, $filteredValue);
+        }
+
+        $isValid  = $this->validatorChain->isValid($filteredValue, $context);
+        $messages = $this->validatorChain->getMessages();
+
+        /**
+         * An empty value should not be considered valid in this situation, regardless
+         * of what the validator chain says.
+         * Instead of mutating the chain, fail validation with a validation failure message that advises the user to
+         * customise the validation chain with a NotEmpty validator.
+         */
+        if ($isValid && $isEmpty) {
+            $isValid  = false;
+            $messages = array_merge([
+                InputInterface::EMPTY_FAILURE_VALIDATION_KEY => sprintf(
+                    'The value for "%s" was empty, but its configuration prohibits an empty value. '
+                    . 'Prepend a "NotEmpty" validator to this input’s chain in order to customise '
+                    . 'this validation failure message',
+                    $this->name,
+                ),
+            ], $messages);
+        }
+
+        return $isValid
+            ? InputValidationResult::pass($this->name, $value, $filteredValue)
+            : InputValidationResult::fail(
+                $this->name,
+                $value,
+                $filteredValue,
+                new ErrorMessages($messages),
+            );
+    }
+
     /** @inheritDoc */
     public function isValid(array|null $context = null): bool
     {
@@ -340,8 +397,7 @@ public function getMessages(): ErrorMessages
             return new ErrorMessages([]);
         }
 
-        $validator = $this->getValidatorChain();
-        return new ErrorMessages($validator->getMessages());
+        return new ErrorMessages($this->validatorChain->getMessages());
     }
 
     protected function injectNotEmptyValidator(): void

src/InputFilterInterface.php

@@ -87,6 +87,14 @@ public function setData(iterable|null $data): static;
      */
     public function isValid(array|null $context = null): bool;
 
+    /**
+     * Is the data set valid?
+     *
+     * @param iterable<array-key, mixed>|null $data
+     * @param array<array-key, mixed>|null $context
+     */
+    public function validate(iterable|null $data, array|null $context = null): InputFilterValidationResult;
+
     /**
      * Provide a list of one or more elements indicating the complete set to validate
      *

src/InputFilterValidationResult.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\InputFilter;
+
+use Laminas\InputFilter\Exception\InputNotFoundException;
+
+final readonly class InputFilterValidationResult implements ValidationResultInterface
+{
+    /** @param array<array-key, self|InputValidationResult> $results */
+    public function __construct(
+        public array $results,
+    ) {
+    }
+
+    public function valid(): bool
+    {
+        foreach ($this->results as $result) {
+            if ($result->valid()) {
+                continue;
+            }
+
+            return false;
+        }
+
+        return true;
+    }
+
+    public function getMessages(): ErrorMessages
+    {
+        $messages = [];
+        foreach ($this->results as $key => $result) {
+            $name            = $this->keyName($key, $result);
+            $messages[$name] = $result->getMessages();
+        }
+
+        return new ErrorMessages($messages);
+    }
+
+    /** @psalm-suppress MixedAssignment */
+    public function rawValue(): array
+    {
+        $value = [];
+        foreach ($this->results as $key => $result) {
+            $name         = $this->keyName($key, $result);
+            $value[$name] = $result->rawValue();
+        }
+
+        return $value;
+    }
+
+    /** @psalm-suppress MixedAssignment */
+    public function value(): array
+    {
+        $value = [];
+        foreach ($this->results as $key => $result) {
+            $name         = $this->keyName($key, $result);
+            $value[$name] = $result->value();
+        }
+
+        return $value;
+    }
+
+    /** @throws InputNotFoundException */
+    public function resultFor(string|int $key): ValidationResultInterface
+    {
+        $result = $this->results[$key] ?? null;
+        if (! $result instanceof ValidationResultInterface) {
+            throw InputNotFoundException::forKey($key);
+        }
+
+        return $result;
+    }
+
+    private function keyName(string|int $key, ValidationResultInterface $result): string|int
+    {
+        return $result instanceof InputValidationResult
+            ? $result->name()
+            : $key;
+    }
+}

src/InputInterface.php

@@ -9,6 +9,9 @@
 
 interface InputInterface
 {
+    /** @internal */
+    public const EMPTY_FAILURE_VALIDATION_KEY = '__inputEmptyValueFailure';
+
     public function setValue(mixed $value): static;
 
     public function allowEmpty(): bool;
@@ -33,6 +36,9 @@ public function getValue(): mixed;
     /** @param array<array-key, mixed>|null $context */
     public function isValid(array|null $context = null): bool;
 
+    /** @param array<array-key, mixed> $context */
+    public function validate(mixed $value, array $context): InputValidationResult;
+
     public function getMessages(): ErrorMessages;
 
     public function continueIfEmpty(): bool;

src/InputValidationResult.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\InputFilter;
+
+final readonly class InputValidationResult implements ValidationResultInterface
+{
+    private function __construct(
+        private int|string $name,
+        private mixed $rawValue,
+        private mixed $value,
+        private bool $valid,
+        private ErrorMessages $errorMessages,
+    ) {
+    }
+
+    public static function pass(
+        int|string $name,
+        mixed $rawValue,
+        mixed $value,
+    ): self {
+        return new self($name, $rawValue, $value, true, new ErrorMessages([]));
+    }
+
+    public static function fail(
+        int|string $name,
+        mixed $rawValue,
+        mixed $value,
+        ErrorMessages $errorMessages,
+    ): self {
+        return new self($name, $rawValue, $value, false, $errorMessages);
+    }
+
+    public function name(): int|string
+    {
+        return $this->name;
+    }
+
+    public function valid(): bool
+    {
+        return $this->valid;
+    }
+
+    public function getMessages(): ErrorMessages
+    {
+        return $this->errorMessages;
+    }
+
+    public function rawValue(): mixed
+    {
+        return $this->rawValue;
+    }
+
+    public function value(): mixed
+    {
+        return $this->value;
+    }
+}

src/ValidationResultInterface.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laminas\InputFilter;
+
+interface ValidationResultInterface
+{
+    public function valid(): bool;
+
+    public function getMessages(): ErrorMessages;
+
+    public function rawValue(): mixed;
+
+    public function value(): mixed;
+}