refactor(validation): move typed access to ValidatedInput

- add ValidatedInput for typed access to validated data
- expose ValidatedInput from Validation and FormRequest
- keep FormRequest focused on request validation flow
- update docs and tests for the new typed input API

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

system/HTTP/FormRequest.php

@@ -13,16 +13,10 @@
 
 namespace CodeIgniter\HTTP;
 
-use BackedEnum;
-use CodeIgniter\Exceptions\InvalidArgumentException;
 use CodeIgniter\Exceptions\RuntimeException;
-use CodeIgniter\I18n\Time;
-use DateTimeZone;
-use Exception;
-use ReflectionEnum;
+use CodeIgniter\Validation\ValidatedInput;
 use ReflectionNamedType;
 use ReflectionParameter;
-use UnitEnum;
 
 /**
  * @see \CodeIgniter\HTTP\FormRequestTest
@@ -189,6 +183,14 @@ public function validated(): array
         return $this->validatedData;
     }
 
+    /**
+     * Returns the validated data as a typed input object.
+     */
+    public function validatedInput(): ValidatedInput
+    {
+        return new ValidatedInput($this->validatedData);
+    }
+
     /**
      * Returns a single validated field value by name, or the default value
      * if the field is not present in the validated data.
@@ -206,134 +208,6 @@ public function getValidated(string $key, mixed $default = null): mixed
         return dot_array_search($key, $this->validatedData);
     }
 
-    /**
-     * Returns a validated field as an integer.
-     *
-     * Supports dot-array syntax for nested validated data.
-     */
-    public function integer(string $key, ?int $default = null): ?int
-    {
-        $value = $this->getValidated($key, $default);
-
-        if ($value === null || is_int($value)) {
-            return $value;
-        }
-
-        if (is_string($value)) {
-            $integer = filter_var($value, FILTER_VALIDATE_INT, FILTER_NULL_ON_FAILURE);
-
-            if ($integer !== null) {
-                return $integer;
-            }
-        }
-
-        throw $this->invalidValidatedType($key, 'integer');
-    }
-
-    /**
-     * Returns a validated field as a boolean.
-     *
-     * Supports dot-array syntax for nested validated data.
-     */
-    public function boolean(string $key, ?bool $default = null): ?bool
-    {
-        $value = $this->getValidated($key, $default);
-
-        if ($value === null || is_bool($value)) {
-            return $value;
-        }
-
-        if (is_int($value) || is_string($value)) {
-            $boolean = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
-
-            if ($boolean !== null) {
-                return $boolean;
-            }
-        }
-
-        throw $this->invalidValidatedType($key, 'boolean');
-    }
-
-    /**
-     * Returns a validated field as a Time instance.
-     *
-     * Supports dot-array syntax for nested validated data.
-     */
-    public function date(
-        string $key,
-        ?string $format = null,
-        DateTimeZone|string|null $timezone = null,
-    ): ?Time {
-        $value = $this->getValidated($key);
-
-        if ($value === null) {
-            return null;
-        }
-
-        if (! is_string($value) || $value === '') {
-            throw $this->invalidValidatedType($key, 'date');
-        }
-
-        try {
-            if ($format === null) {
-                return Time::parse($value, $timezone);
-            }
-
-            return Time::createFromFormat($format, $value, $timezone);
-        } catch (Exception) {
-            throw $this->invalidValidatedType($key, 'date');
-        }
-    }
-
-    /**
-     * Returns a validated field as an enum instance.
-     *
-     * Supports dot-array syntax for nested validated data.
-     *
-     * @template TEnum of UnitEnum
-     *
-     * @param class-string<TEnum> $enumClass
-     * @param TEnum|null          $default
-     *
-     * @return TEnum|null
-     */
-    public function enum(string $key, string $enumClass, ?UnitEnum $default = null): ?UnitEnum
-    {
-        if (! enum_exists($enumClass)) {
-            throw new InvalidArgumentException('The "' . $enumClass . '" class is not a valid enum.');
-        }
-
-        $value = $this->getValidated($key, $default);
-
-        if ($value === null) {
-            return null;
-        }
-
-        if ($value instanceof UnitEnum) {
-            if ($value instanceof $enumClass) {
-                return $value;
-            }
-
-            throw $this->invalidValidatedType($key, $enumClass);
-        }
-
-        $reflection = new ReflectionEnum($enumClass);
-
-        if ($reflection->isBacked()) {
-            return $this->backedEnum($key, $enumClass, $reflection, $value);
-        }
-
-        if (is_string($value)) {
-            foreach ($enumClass::cases() as $case) {
-                if ($case->name === $value) {
-                    return $case;
-                }
-            }
-        }
-
-        throw $this->invalidValidatedType($key, $enumClass);
-    }
-
     /**
      * Returns true when the named field exists in the validated data, even if
      * its value is null.
@@ -347,46 +221,6 @@ public function hasValidated(string $key): bool
         return dot_array_has($key, $this->validatedData);
     }
 
-    private function backedEnum(string $key, string $enumClass, ReflectionEnum $reflection, mixed $value): UnitEnum
-    {
-        $backingType = $reflection->getBackingType()?->getName();
-
-        if ($backingType === 'int') {
-            if (is_string($value)) {
-                $value = filter_var($value, FILTER_VALIDATE_INT, FILTER_NULL_ON_FAILURE);
-            }
-
-            if (! is_int($value)) {
-                throw $this->invalidValidatedType($key, $enumClass);
-            }
-        } elseif (! is_int($value) && ! is_string($value)) {
-            throw $this->invalidValidatedType($key, $enumClass);
-        }
-
-        if (! is_subclass_of($enumClass, BackedEnum::class)) {
-            throw $this->invalidValidatedType($key, $enumClass);
-        }
-
-        if ($backingType === 'string') {
-            $value = (string) $value;
-        }
-
-        $enum = $enumClass::tryFrom($value);
-
-        if ($enum === null) {
-            throw $this->invalidValidatedType($key, $enumClass);
-        }
-
-        return $enum;
-    }
-
-    private function invalidValidatedType(string $key, string $type): InvalidArgumentException
-    {
-        return new InvalidArgumentException(
-            sprintf('The validated "%s" value cannot be read as %s.', $key, $type),
-        );
-    }
-
     /**
      * Returns the data to be validated.
      *