feat(validation): support skipping missing properties

docs/2-features/03-validation.md

@@ -76,6 +76,22 @@ final class Book
 }
 ```
 
+Use {b`#[Tempest\Validation\SkipIfMissing]`} when a property should only be validated when its value is present. Missing properties remain uninitialized when mapping, which is useful for partial updates.
+
+```php
+use Tempest\Validation\Rules\IsNotEmptyString;
+use Tempest\Validation\SkipIfMissing;
+
+final class UpdateBook
+{
+    #[SkipIfMissing, IsNotEmptyString]
+    public string $title;
+
+    #[SkipIfMissing]
+    public ?DateTime $publishedAt;
+}
+```
+
 ## Validating an existing object instance
 
 When you already have an instantiated object, you may use the `validateObject()` method. Unlike `validateValuesForClass()`, this method takes an object instance and reads the actual values of its public properties directly.

packages/validation/src/SkipIfMissing.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Validation;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class SkipIfMissing {}

packages/validation/src/Validator.php

@@ -98,7 +98,7 @@ public function validateValuesForClass(ClassReflector|string $class, ?array $val
 
             $key = $prefix . $property->getName();
 
-            if (! $values->hasKey($key) && $property->hasDefaultValue()) {
+            if (! $values->hasKey($key) && ($property->hasDefaultValue() || $property->hasAttribute(SkipIfMissing::class))) {
                 continue;
             }
 

tests/Integration/Route/Fixtures/RequestWithOptionalProperties.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Tests\Tempest\Integration\Route\Fixtures;
+
+use Tempest\Validation\Rules\IsNotEmptyString;
+use Tempest\Validation\SkipIfMissing;
+
+final class RequestWithOptionalProperties
+{
+    #[SkipIfMissing, IsNotEmptyString]
+    public string $title;
+
+    #[SkipIfMissing]
+    public ?string $expiryDate;
+}

tests/Integration/Route/RequestToObjectMapperTest.php

@@ -3,6 +3,7 @@
 namespace Tests\Tempest\Integration\Route;
 
 use Laminas\Diactoros\UploadedFile;
+use ReflectionProperty;
 use Tempest\Http\GenericRequest;
 use Tempest\Http\Mappers\PsrRequestToGenericRequestMapper;
 use Tempest\Http\Mappers\RequestToObjectMapper;
@@ -16,6 +17,7 @@
 use Tests\Tempest\Integration\Route\Fixtures\EnumForRequest;
 use Tests\Tempest\Integration\Route\Fixtures\RequestObjectA;
 use Tests\Tempest\Integration\Route\Fixtures\RequestWithEnum;
+use Tests\Tempest\Integration\Route\Fixtures\RequestWithOptionalProperties;
 use Tests\Tempest\Integration\Route\Fixtures\RequestWithTypedQueryParam;
 
 use function Tempest\Mapper\map;
@@ -143,4 +145,34 @@ public function test_missing_enum_value(): void
             $this->assertInstanceOf(IsNotNull::class, $validationFailed->failingRules['enumParam'][0]->rule);
         }
     }
+
+    public function test_missing_optional_properties_are_not_initialized(): void
+    {
+        $request = map(new GenericRequest(
+            method: Method::PATCH,
+            uri: '/',
+            body: ['expiryDate' => null],
+        ))->with(
+            RequestToObjectMapper::class,
+        )->to(RequestWithOptionalProperties::class);
+
+        $this->assertFalse(new ReflectionProperty($request, 'title')->isInitialized($request));
+        $this->assertTrue(new ReflectionProperty($request, 'expiryDate')->isInitialized($request));
+        $this->assertNull($request->expiryDate);
+    }
+
+    public function test_present_optional_properties_are_validated(): void
+    {
+        $this->assertException(
+            expectedExceptionClass: ValidationFailed::class,
+            handler: fn () => map(new GenericRequest(
+                method: Method::PATCH,
+                uri: '/',
+                body: ['title' => ''],
+            ))->with(
+                RequestToObjectMapper::class,
+            )->to(RequestWithOptionalProperties::class),
+            assertException: fn (ValidationFailed $exception) => $this->assertArrayHasKey('title', $exception->failingRules),
+        );
+    }
 }