andreypostal · andreypostal · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025
diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@ use \Andrey\PancakeObject\Attributes\Item;
 class MyObject {
     #[Item]
     public int $id;
-    #[Item]
+    #[Item(default: 'default name')]
     public string $name;
 }
 ```
@@ -110,6 +110,19 @@ class MyObject {
 
 The type option can be used to validate that all the items in an array have some desired type as well, like "string", "integer"...
 
+You can define a default value for an item using the "default" field when using the Item attribute:
+
+```php
+use \Andrey\PancakeObject\Attributes\Item;
+
+class MyObject {
+    #[Item]
+    public int $id;
+    #[Item(default: 'default name')]
+    public string $name;
+}
+```
+
 ### Hydrator and Serializer
 
 In order to hydrate some value object following the attribute rules, you just need to use the SimpleHydrator class.

diff --git a/src/Attributes/Item.php b/src/Attributes/Item.php
@@ -10,5 +10,6 @@ public function __construct(
         public ?string $key = null,
         public bool $required = false,
         public ?string $type = null,
+        public mixed $default = null,
     ) { }
 }
diff --git a/src/SimpleHydrator.php b/src/SimpleHydrator.php
@@ -89,7 +89,7 @@ private function processProperty(ReflectionProperty $property, array $data, bool
         }
 
         if (!$arrKeyExists) {
-            return $this->buildNullableResponse($property, null);
+            return $this->buildNullableResponse($property, $item->default);
         }
 
         if ($property->getType()?->isBuiltin()) {
@@ -134,7 +134,7 @@ private function handleBuiltin(array $data, string $key, ReflectionProperty $pro
             return new Payload(data: $output);
         }
 
-        // If no data is set, returns null which will be ignored by the set value, falling back to undefined or default value
+        // If no data is set, return null, which will be ignored by the set value, falling back to undefined or default value
         return $this->buildNullableResponse($property, $data[$key] ?? null);
     }
 

diff --git a/tests/HydratorTest.php b/tests/HydratorTest.php
@@ -158,4 +158,23 @@ public function testArrayWithWrongValuesWithChild(): void
         $this->expectExceptionMessage('expected array with items of type <Utils\ChildObject> but found <string>');
         $hydrator->hydrate($data, TestObject::class);
     }
+
+    /**
+     * @throws ReflectionException
+     */
+    public function testDefaultValueFromItem(): void
+    {
+        $data = [
+            'missing_required' => 'Im here',
+        ];
+
+        $hydrator = new SimpleHydrator();
+        /** @var TestObject $object */
+        $object = $hydrator->hydrate($data, TestObject::class);
+
+        $this->assertEquals('default name', $object->itemName);
+        $this->assertEquals(ChildObject::class, $object->singleChild::class);
+        $this->assertCount(0, $object->singleChild->andImAnArrayOfInt);
+        $this->assertEquals('default child name', $object->singleChild->iHaveAName);
+    }
 }
diff --git a/tests/Utils/TestObject.php b/tests/Utils/TestObject.php
@@ -44,13 +44,13 @@ public function __construct(
     #[Item(type: ImEnum::class)]
     public array $enumArr;
 
-    #[Item]
+    #[Item(default: 'default name')]
     public string $itemName;
 
     #[Item(required: true)]
     public string $missingRequired;
 
-    #[Item]
+    #[Item(default: new ChildObject('default child name', 'different one', []))]
     public ChildObject $singleChild;
 
     #[Item]