Merge pull request #174 from patchlevel/object-to-populate

add object to populate feature

Author: DavidBadura

README.md

@@ -125,6 +125,24 @@ $oldEvent == $event // true
 > [!WARNING]
 > It is important to know that the constructor is not called!
 
+#### Object to populate
+
+If you want to hydrate an object that already exists, you can specify the object to populate.
+This is useful if you want to update an existing object.
+
+```php
+$dto = new Dto();
+
+$event = $hydrator->hydrate(
+    $dto::class,
+    [
+      'name' => 'patchlevel',
+    ], [
+        MetadataHydrator::OBJECT_TO_POPULATE => $dto,
+    ],
+);
+```
+
 ### Normalizer
 
 For more complex structures, i.e. non-scalar data types, we use normalizers.

phpstan-baseline.neon

@@ -114,6 +114,36 @@ parameters:
 			count: 3
 			path: src/Metadata/AttributeMetadataFactory.php
 
+		-
+			message: '#^Method Patchlevel\\Hydrator\\MetadataHydrator\:\:doHydrate\(\) should return T of object but returns mixed\.$#'
+			identifier: return.type
+			count: 1
+			path: src/MetadataHydrator.php
+
+		-
+			message: '#^Parameter \#1 \$object of method Patchlevel\\Hydrator\\Metadata\\CallbackMetadata\:\:invoke\(\) expects object, mixed given\.$#'
+			identifier: argument.type
+			count: 1
+			path: src/MetadataHydrator.php
+
+		-
+			message: '#^Parameter \#1 \$object of method Patchlevel\\Hydrator\\Metadata\\PropertyMetadata\:\:setValue\(\) expects object, mixed given\.$#'
+			identifier: argument.type
+			count: 2
+			path: src/MetadataHydrator.php
+
+		-
+			message: '#^Method Patchlevel\\Hydrator\\Middleware\\TransformMiddleware\:\:hydrate\(\) should return T of object but returns mixed\.$#'
+			identifier: return.type
+			count: 1
+			path: src/Middleware/TransformMiddleware.php
+
+		-
+			message: '#^Parameter \#1 \$object of method Patchlevel\\Hydrator\\Metadata\\PropertyMetadata\:\:setValue\(\) expects object, mixed given\.$#'
+			identifier: argument.type
+			count: 2
+			path: src/Middleware/TransformMiddleware.php
+
 		-
 			message: '#^Property Patchlevel\\Hydrator\\Normalizer\\EnumNormalizer\:\:\$enum \(class\-string\<BackedEnum\>\|null\) does not accept string\.$#'
 			identifier: assign.propertyType

src/HydratorWithContext.php

@@ -6,6 +6,8 @@
 
 interface HydratorWithContext extends Hydrator
 {
+    public const OBJECT_TO_POPULATE = 'object_to_populate';
+
     /**
      * @param class-string<T>      $class
      * @param array<string, mixed> $data

src/MetadataHydrator.php

@@ -104,7 +104,8 @@ private function doHydrate(ClassMetadata $metadata, array $data, array $context
             $data = $this->eventDispatcher->dispatch(new PreHydrate($data, $metadata))->data;
         }
 
-        $object = $metadata->newInstance();
+        $object = $context[self::OBJECT_TO_POPULATE] ?? $metadata->newInstance();
+        unset($context[self::OBJECT_TO_POPULATE]);
 
         $constructorParameters = null;
 

src/Middleware/TransformMiddleware.php

@@ -6,6 +6,7 @@
 
 use Patchlevel\Hydrator\CircularReference;
 use Patchlevel\Hydrator\DenormalizationFailure;
+use Patchlevel\Hydrator\HydratorWithContext;
 use Patchlevel\Hydrator\Metadata\ClassMetadata;
 use Patchlevel\Hydrator\NormalizationFailure;
 use Patchlevel\Hydrator\Normalizer\NormalizerWithContext;
@@ -34,7 +35,8 @@ final class TransformMiddleware implements Middleware
      */
     public function hydrate(ClassMetadata $metadata, array $data, array $context, Stack $stack): object
     {
-        $object = $metadata->newInstance();
+        $object = $context[HydratorWithContext::OBJECT_TO_POPULATE] ?? $metadata->newInstance();
+        unset($context[HydratorWithContext::OBJECT_TO_POPULATE]);
 
         $constructorParameters = null;
 

tests/Unit/MetadataHydratorTest.php

@@ -291,6 +291,22 @@ public function testHydrateWithInlineNormalizer(): void
         self::assertEquals($expected, $event);
     }
 
+    public function testHydrateWithObjectToPopulate(): void
+    {
+        $id = ProfileId::fromString('1');
+        $dto = new ProfileCreated($id, Email::fromString('foo@patchlevel.de'));
+
+        $processedDto = $this->hydrator->hydrate(
+            $dto::class,
+            ['email' => 'other@patchlevel.de'],
+            [MetadataHydrator::OBJECT_TO_POPULATE => $dto],
+        );
+
+        self::assertSame($dto, $processedDto);
+        self::assertSame($id, $processedDto->profileId);
+        self::assertEquals(Email::fromString('other@patchlevel.de'), $processedDto->email);
+    }
+
     public function testDenormalizationFailure(): void
     {
         $this->expectException(DenormalizationFailure::class);

tests/Unit/StackHydratorTest.php

@@ -311,6 +311,22 @@ public function testHydrateWithContext(): void
         self::assertEquals($expect, $object);
     }
 
+    public function testHydrateWithObjectToPopulate(): void
+    {
+        $id = ProfileId::fromString('1');
+        $dto = new ProfileCreated($id, Email::fromString('foo@patchlevel.de'));
+
+        $processedDto = $this->hydrator->hydrate(
+            $dto::class,
+            ['email' => 'other@patchlevel.de'],
+            [StackHydrator::OBJECT_TO_POPULATE => $dto],
+        );
+
+        self::assertSame($dto, $processedDto);
+        self::assertSame($id, $processedDto->profileId);
+        self::assertEquals(Email::fromString('other@patchlevel.de'), $processedDto->email);
+    }
+
     #[RequiresPhp('>=8.5')]
     public function testHydrateWithInlineNormalizer(): void
     {