feat(validation): add date default to validated input

- Allow date() to return a Time default for missing fields
- Keep explicit null and invalid present values behavior unchanged
- Document strict ValidatedInput behavior and thrown exceptions
- Cover date defaults in tests and user guide

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

Author: memleakd

system/Validation/ValidatedInput.php

@@ -22,6 +22,11 @@
 use UnitEnum;
 
 /**
+ * Represents validated input data.
+ *
+ * This class is stricter than InputData: missing values may use defaults and
+ * null values remain null, but invalid present values throw.
+ *
  * @see \CodeIgniter\Validation\ValidatedInputTest
  */
 class ValidatedInput extends InputData
@@ -30,12 +35,19 @@ class ValidatedInput extends InputData
      * Returns a validated field as a Time instance.
      *
      * Supports dot-array syntax for nested validated data.
+     *
+     * @throws InvalidArgumentException
      */
     public function date(
         string $key,
         ?string $format = null,
         DateTimeZone|string|null $timezone = null,
+        ?Time $default = null,
     ): ?Time {
+        if (! $this->has($key)) {
+            return $default;
+        }
+
         $value = $this->get($key);
 
         if ($value === null) {
@@ -68,6 +80,8 @@ public function date(
      * @param TEnum|null          $default
      *
      * @return TEnum|null
+     *
+     * @throws InvalidArgumentException
      */
     public function enum(string $key, string $enumClass, ?UnitEnum $default = null): ?UnitEnum
     {

tests/system/Validation/ValidatedInputTest.php

@@ -51,6 +51,14 @@ public function testDateSupportsCustomFormat(): void
         $this->assertSame('2026-05-04', $input->date('published_at', 'd/m/Y')->toDateString());
     }
 
+    public function testDateReturnsDefaultForMissingValidatedField(): void
+    {
+        $input   = new ValidatedInput([]);
+        $default = Time::parse('2026-05-04');
+
+        $this->assertSame($default, $input->date('published_at', default: $default));
+    }
+
     public function testDateThrowsForInvalidValidatedValue(): void
     {
         $input = new ValidatedInput(['published_at' => '']);
@@ -165,8 +173,9 @@ public function testTypedAccessorsReturnNullForNullValidatedFields(): void
             'published_at' => null,
             'status'       => null,
         ]);
+        $default = Time::parse('2026-05-04');
 
-        $this->assertNotInstanceOf(Time::class, $input->date('published_at'));
+        $this->assertNull($input->date('published_at', default: $default));
         $this->assertNotInstanceOf(StatusEnum::class, $input->enum('status', StatusEnum::class, StatusEnum::PENDING));
     }
 }

user_guide_src/source/libraries/validation.rst

@@ -521,9 +521,10 @@ All methods support dot-array syntax for nested validated data.
   missing, it returns the default value or ``null``.
 * ``array($key, $default = null)`` returns ``array|null``. If the field is
   missing, it returns the default value or ``null``.
-* ``date($key, $format = null, $timezone = null)`` returns
-  :php:class:`CodeIgniter\\I18n\\Time` or ``null``. Pass a format when the value
-  should be parsed with a specific date format.
+* ``date($key, $format = null, $timezone = null, $default = null)`` returns
+  :php:class:`CodeIgniter\\I18n\\Time` or ``null``. If the field is missing, it
+  returns the default value or ``null``. Pass a format when the value should be
+  parsed with a specific date format.
 * ``enum($key, $enumClass, $default = null)`` returns an enum instance or
   ``null``. The default value must be ``null`` or an instance of the requested
   enum class.