feat(http): add typed FormRequest accessors

- Add typed helpers for reading validated integer, boolean, date, and enum values
- Keep accessors scoped to validated FormRequest data only
- Document expected validation/accessor responsibilities
- Cover defaults, null values, invalid values, dot syntax, and enum variants

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

Author: memleakd

system/HTTP/FormRequest.php

@@ -13,9 +13,16 @@
 
 namespace CodeIgniter\HTTP;
 
+use BackedEnum;
+use CodeIgniter\Exceptions\InvalidArgumentException;
 use CodeIgniter\Exceptions\RuntimeException;
+use CodeIgniter\I18n\Time;
+use DateTimeZone;
+use Exception;
+use ReflectionEnum;
 use ReflectionNamedType;
 use ReflectionParameter;
+use UnitEnum;
 
 /**
  * @see \CodeIgniter\HTTP\FormRequestTest
@@ -199,6 +206,134 @@ 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.
@@ -212,6 +347,46 @@ 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.
      *