Add nested mapping support via new ObjectMap class

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 1.5.1 under development
 
-- no changes in this release.
+- New #63: Add nested mapping support via new `ObjectMap` class (@vjik)
 
 ## 1.5.0 September 17, 2024
 

docs/guide/en/mapping.md

@@ -44,6 +44,40 @@ $post = $hydrator->create(Post::class, new ArrayData($data, $map));
 
 This way we take `header` key for `title` and `text` key for `body`.
 
+For nested objects mapping you can use `ObjectMap` class:
+
+```php
+use Yiisoft\Hydrator\ArrayData;
+use Yiisoft\Hydrator\Hydrator;
+use Yiisoft\Hydrator\ObjectMap;
+
+final class Message {
+ public string $subject = '';
+ public ?Body $body = null;
+}
+
+final class Body {
+ public string $text = '';
+ public string $html = '';
+}
+
+$hydrator = new Hydrator();
+
+$data = [
+ 'title' => 'Hello, World!',
+ 'textBody' => 'Nice to meet you.',
+ 'htmlBody' => '<h1>Nice to meet you.</h1>',
+];
+$map = [
+ 'subject' => 'title',
+ 'body' => new ObjectMap([
+ 'text' => 'textBody',
+ 'html' => 'htmlBody', 
+ ]), 
+];
+$message = $hydrator->create(Message::class, new ArrayData($data, $map));
+```
+
 ## Strict mode
 
 You can enable strict mode by passing `true` as a third argument of `ArrayData`:
@@ -54,7 +88,7 @@ use Yiisoft\Hydrator\ArrayData;
 
 $hydrator = new Hydrator();
 
-$map = ['title' => 'header', 'body' => 'text'],;
+$map = ['title' => 'header', 'body' => 'text'];
 $post = $hydrator->create(Post::class, new ArrayData($data, $map, true));
 ```
 

phpunit.xml.dist

@@ -11,6 +11,7 @@
  failOnWarning="true"
  stopOnFailure="false"
  colors="true"
+ displayDetailsOnPhpunitDeprecations="true"
 >
  <php>
  <ini name="error_reporting" value="-1"/>

src/ArrayData.php

@@ -6,40 +6,65 @@
 
 use Yiisoft\Strings\StringHelper;
 
-use function array_key_exists;
 use function is_array;
 use function is_string;
 use function strlen;
 
 /**
  * Holds data to hydrate an object from and a map to use when populating an object.
  *
- * @psalm-type MapType=array<string,string|list<string>>
+ * @psalm-type MapType=array<string,string|list<string>|ObjectMap>
  */
 final class ArrayData implements DataInterface
 {
+ private readonly ObjectMap $objectMap;
+
  /**
  * @param array $data Data to hydrate object from.
- * @param array $map Object property names mapped to keys in the data array that hydrator will use when hydrating
- * an object.
+ * @param array|ObjectMap $map Object property names mapped to keys in the data array that hydrator will use when
+ * hydrating an object.
  * @param bool $strict Whether to hydrate properties from the map only.
  *
- * @psalm-param MapType $map
+ * @psalm-param ObjectMap|MapType $map
  */
  public function __construct(
- private array $data = [],
- private array $map = [],
- private bool $strict = false,
+ private readonly array $data = [],
+ array|ObjectMap $map = [],
+ private readonly bool $strict = false,
  ) {
+ $this->objectMap = is_array($map) ? new ObjectMap($map) : $map;
  }
 
  public function getValue(string $name): Result
  {
- if ($this->strict && !array_key_exists($name, $this->map)) {
+ if ($this->strict && !$this->objectMap->exists($name)) {
  return Result::fail();
  }
 
- return $this->getValueByPath($this->data, $this->map[$name] ?? $name);
+ $path = $this->objectMap->getPath($name) ?? $name;
+ if ($path instanceof ObjectMap) {
+ return $this->getValueByObjectMap($this->data, $path);
+ }
+
+ return $this->getValueByPath($this->data, $path);
+ }
+
+ /**
+ * Get an array given a map as resolved result.
+ */
+ private function getValueByObjectMap(array $data, ObjectMap $objectMap): Result
+ {
+ $arrayData = new self($data, $objectMap);
+
+ $result = [];
+ foreach ($objectMap->getNames() as $name) {
+ $value = $arrayData->getValue($name);
+ if ($value->isResolved()) {
+ $result[$name] = $value->getValue();
+ }
+ }
+
+ return Result::success($result);
  }
 
  /**

src/ObjectMap.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator;
+
+use function array_key_exists;
+
+/**
+ * Class provides mapping object property names to keys in the data array.
+ *
+ * @psalm-import-type MapType from ArrayData
+ */
+final class ObjectMap
+{
+ /**
+ * @param array $map Object property names mapped to keys in the data array that hydrator will use when hydrating
+ * an object.
+ * @psalm-param MapType $map
+ */
+ public function __construct(
+ public readonly array $map
+ ) {
+ }
+
+ /**
+ * @psalm-return string|list<string>|ObjectMap|null
+ */
+ public function getPath(string $name): string|array|self|null
+ {
+ return $this->map[$name] ?? null;
+ }
+
+ /**
+ * @return string[]
+ * @psalm-return list<string>
+ */
+ public function getNames(): array
+ {
+ return array_keys($this->map);
+ }
+
+ public function exists(string $name): bool
+ {
+ return array_key_exists($name, $this->map);
+ }
+}

tests/ObjectMap/Nested.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Tests\ObjectMap;
+
+final class Nested
+{
+ public string $var = '';
+ public ?Nested2 $nested2 = null;
+}

tests/ObjectMap/Nested2.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Tests\ObjectMap;
+
+final class Nested2
+{
+ public string $var1 = '';
+ public string $var2 = '';
+}

tests/ObjectMap/ObjectMapTest.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Tests\ObjectMap;
+
+use PHPUnit\Framework\TestCase;
+use Yiisoft\Hydrator\ArrayData;
+use Yiisoft\Hydrator\Hydrator;
+use Yiisoft\Hydrator\ObjectMap;
+
+final class ObjectMapTest extends TestCase
+{
+ public function testBase(): void
+ {
+ $hydrator = new Hydrator();
+
+ $root = $hydrator->create(
+ Root::class,
+ new ArrayData(
+ ['key' => 'test'],
+ ['nested' => new ObjectMap(['var' => 'key'])],
+ ),
+ );
+
+ $this->assertSame('test', $root->nested?->var);
+ $this->assertNull($root->nested->nested2);
+ }
+
+ public function testNested2(): void
+ {
+ $hydrator = new Hydrator();
+
+ $root = $hydrator->create(
+ Root::class,
+ new ArrayData(
+ ['a' => 'A', 'b' => ['b1' => 'B1'], 'c' => 'C'],
+ [
+ 'nested' => new ObjectMap([
+ 'var' => 'a',
+ 'nested2' => new ObjectMap([
+ 'var1' => ['b', 'b1'],
+ 'var2' => 'c',
+ ]),
+ ]),
+ ],
+ ),
+ );
+
+ $this->assertSame('A', $root->nested?->var);
+ $this->assertSame('B1', $root->nested?->nested2?->var1);
+ $this->assertSame('C', $root->nested?->nested2?->var2);
+ }
+
+ public function testWithSameKeyInData(): void
+ {
+ $hydrator = new Hydrator();
+
+ $root = $hydrator->create(
+ Root::class,
+ new ArrayData(
+ [
+ 'var' => 'test',
+ 'var1' => 'A',
+ 'var2' => 'B',
+ ],
+ [
+ 'nested' => new ObjectMap([
+ 'nested2' => new ObjectMap([
+ 'var1' => 'var',
+ ]),
+ ]),
+ ],
+ ),
+ );
+
+ $this->assertSame('', $root->nested?->var);
+ $this->assertSame('test', $root->nested?->nested2?->var1);
+ $this->assertSame('', $root->nested?->nested2?->var2);
+ }
+
+ public function testWithoutMap(): void
+ {
+ $hydrator = new Hydrator();
+
+ $root = $hydrator->create(
+ Root::class,
+ new ArrayData(
+ [
+ 'nested' => [
+ 'nested2' => [
+ 'var1' => 'A',
+ 'var2' => 'B',
+ ],
+ ],
+ ],
+ ),
+ );
+
+ $this->assertSame('A', $root->nested?->nested2?->var1);
+ $this->assertSame('B', $root->nested?->nested2?->var2);
+ }
+}

tests/ObjectMap/Readme/Body.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Tests\ObjectMap\Readme;
+
+final class Body
+{
+ public string $text = '';
+ public string $html = '';
+}

tests/ObjectMap/Readme/Message.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Tests\ObjectMap\Readme;
+
+final class Message
+{
+ public string $subject = '';
+ public ?Body $body = null;
+}

tests/ObjectMap/Readme/ObjectMapReadmeTest.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Tests\ObjectMap\Readme;
+
+use PHPUnit\Framework\TestCase;
+use Yiisoft\Hydrator\ArrayData;
+use Yiisoft\Hydrator\Hydrator;
+use Yiisoft\Hydrator\ObjectMap;
+
+final class ObjectMapReadmeTest extends TestCase
+{
+ public function testBase(): void
+ {
+ $hydrator = new Hydrator();
+ $data = [
+ 'title' => 'Hello, World!',
+ 'textBody' => 'Nice to meet you.',
+ 'htmlBody' => '<h1>Nice to meet you.</h1>',
+ ];
+ $map = [
+ 'subject' => 'title',
+ 'body' => new ObjectMap([
+ 'text' => 'textBody',
+ 'html' => 'htmlBody',
+ ]),
+ ];
+
+ $message = $hydrator->create(Message::class, new ArrayData($data, $map));
+
+ $this->assertSame('Hello, World!', $message->subject);
+ $this->assertSame('Nice to meet you.', $message->body?->text);
+ $this->assertSame('<h1>Nice to meet you.</h1>', $message->body?->html);
+ }
+}

tests/ObjectMap/Root.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Tests\ObjectMap;
+
+final class Root
+{
+ public ?Nested $nested = null;
+}