Add support for collections

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 1.3.0 under development
 
+- New #49: Add support for collections (@arogachev) 
 - Enh #85: Allow to hydrate non-initialized readonly properties (@vjik)
 
 ## 1.2.0 April 03, 2024

docs/guide/en/typecasting.md

@@ -20,9 +20,10 @@ $lock = $hydrator->create(Lock::class, ['name' => 'The lock', 'isLocked' => 1]);
 You can adjust type-casting by passing a type-caster to the hydrator:
 
 ```php
+use Yiisoft\Hydrator\Hydrator;
 use Yiisoft\Hydrator\TypeCaster\CompositeTypeCaster;
 use Yiisoft\Hydrator\TypeCaster\PhpNativeTypeCaster;
-use Yiisoft\Hydrator\TypeCaster\HydratorTypeCaster
+use Yiisoft\Hydrator\TypeCaster\HydratorTypeCaster;
 
 $typeCaster = new CompositeTypeCaster(
     new PhpNativeTypeCaster(),
@@ -119,6 +120,8 @@ echo $post->getAuthor()->getNickName();
 
 ## Using attributes
 
+### Strings
+
 To cast a value to string explicitly, you can use `ToString` attribute:
 
 ```php
@@ -139,6 +142,26 @@ $money = $hydrator->create(Money::class, [
 ]);
 ```
 
+To strip whitespace (or other characters) from the beginning and/or end of a resolved string value, you can use `Trim`,
+`LeftTrim` or `RightTrim` attributes:
+
+```php
+use DateTimeImmutable;
+use Yiisoft\Hydrator\Attribute\Parameter\Trim;
+
+class Person
+{
+    public function __construct(
+        #[Trim] // '  John ' → 'John'
+        private ?string $name = null, 
+    ) {}
+}
+
+$person = $hydrator->create(Person::class, ['name' => '  John ']);
+```
+
+### Datetime
+
 To cast a value to `DateTimeImmutable` or `DateTime` object explicitly, you can use `ToDateTime` attribute:
 
 ```php
@@ -156,20 +179,94 @@ class Person
 $person = $hydrator->create(Person::class, ['birthday' => '27.01.1986']);
 ```
 
-To strip whitespace (or other characters) from the beginning and/or end of a resolved string value, you can use `Trim`, 
-`LeftTrim` or `RightTrim` attributes:
+### Collections
+
+Hydrator supports collections via `Collection` attribute. The class name of related collection must be specified:                                
 
 ```php
-use DateTimeImmutable;
-use Yiisoft\Hydrator\Attribute\Parameter\Trim;
+final class PostCategory
+{
+    public function __construct(
+        #[Collection(Post::class)]
+        private array $posts = [],
+    ) {
+    }
+}
 
-class Person
+final class Post
 {
     public function __construct(
-        #[Trim] // '  John ' → 'John'
-        private ?string $name = null, 
-    ) {}
+        private string $name,
+        private string $description = '',
+    ) {
+    }
 }
 
-$person = $hydrator->create(Person::class, ['name' => '  John ']);
+$category = $hydrator->create(
+    PostCategory::class,
+    [
+        ['name' => 'Post 1'],
+        ['name' => 'Post 2', 'description' => 'Description for post 2'],
+    ],
+);
+```
+
+One-to-many relations can be nested and combined with one-to-one relations:
+
+```php
+final class ChartSet
+{
+    public function __construct(
+        #[Collection(Chart::class)]
+        private array $charts = [],
+    ) {
+    }
+}
+
+final class Chart
+{
+    public function __construct(
+        #[Collection(Point::class)]
+        private array $points,
+    ) {
+    }
+}
+
+final class Point
+{
+    public function __construct(
+        private Coordinates $coordinates,
+        private array $rgb,
+    ) {
+    }
+}
+
+final class Coordinates
+{
+    public function __construct(
+        private int $x,
+        private int $y,
+    ) {
+    }
+}
+
+$object = $hydrator->create(
+    ChartSet::class,
+    [
+        'charts' => [
+            [
+                'points' => [
+                    ['coordinates' => ['x' => 1, 'y' => 1], 'rgb' => [0, 0, 0]],
+                    ['coordinates' => ['x' => 2, 'y' => 2], 'rgb' => [0, 0, 0]],
+                ],
+            ],
+            [
+                'points' => [
+                    ['coordinates' => ['x' => 3, 'y' => 3], 'rgb' => [0, 0, 0]],
+                    ['coordinates' => ['x' => 4, 'y' => 4], 'rgb' => [0, 0, 0]],
+                ],
+            ],
+        ],
+    ],
+);
 ```

src/Attribute/Parameter/Collection.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Attribute\Parameter;
+
+use Attribute;
+
+/**
+ * Converts the resolved value to array of instances of the class specified in {@see Collection::$className}.
+ * Non-resolved and invalid values are skipped.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_PARAMETER | Attribute::IS_REPEATABLE)]
+final class Collection implements ParameterAttributeInterface
+{
+    /**
+     * @psalm-param class-string $className
+     */
+    public function __construct(
+        public readonly string $className,
+    ) {
+    }
+
+    public function getResolver(): string
+    {
+        return CollectionResolver::class;
+    }
+}

src/Attribute/Parameter/CollectionResolver.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Hydrator\Attribute\Parameter;
+
+use Yiisoft\Hydrator\AttributeHandling\Exception\UnexpectedAttributeException;
+use Yiisoft\Hydrator\AttributeHandling\ParameterAttributeResolveContext;
+use Yiisoft\Hydrator\DataInterface;
+use Yiisoft\Hydrator\Result;
+
+final class CollectionResolver implements ParameterAttributeResolverInterface
+{
+    public function getParameterValue(
+        ParameterAttributeInterface $attribute,
+        ParameterAttributeResolveContext $context,
+    ): Result {
+        if (!$attribute instanceof Collection) {
+            throw new UnexpectedAttributeException(Collection::class, $attribute);
+        }
+
+        if (!$context->isResolved()) {
+            return Result::fail();
+        }
+
+        $resolvedValue = $context->getResolvedValue();
+        if (!is_iterable($resolvedValue)) {
+            return Result::fail();
+        }
+
+        $collection = [];
+        foreach ($context->getResolvedValue() as $item) {
+            if (!is_array($item) && !$item instanceof DataInterface) {
+                return Result::fail();
+            }
+
+            $collection[] = $context->getHydrator()->create($attribute->className, $item);
+        }
+
+        return Result::success($collection);
+    }
+}

src/AttributeHandling/ParameterAttributeResolveContext.php

@@ -7,6 +7,7 @@
 use ReflectionParameter;
 use ReflectionProperty;
 use Yiisoft\Hydrator\DataInterface;
+use Yiisoft\Hydrator\HydratorInterface;
 use Yiisoft\Hydrator\Result;
 
 /**
@@ -23,6 +24,7 @@ public function __construct(
         private ReflectionParameter|ReflectionProperty $parameter,
         private Result $resolveResult,
         private DataInterface $data,
+        private HydratorInterface $hydrator,
     ) {
     }
 
@@ -66,4 +68,9 @@ public function getData(): DataInterface
     {
         return $this->data;
     }
+
+    public function getHydrator(): HydratorInterface
+    {
+        return $this->hydrator;
+    }
 }

src/AttributeHandling/ParameterAttributesHandler.php

@@ -13,6 +13,7 @@
 use Yiisoft\Hydrator\Attribute\Parameter\ParameterAttributeResolverInterface;
 use Yiisoft\Hydrator\ArrayData;
 use Yiisoft\Hydrator\DataInterface;
+use Yiisoft\Hydrator\HydratorInterface;
 use Yiisoft\Hydrator\Result;
 
 /**
@@ -22,6 +23,7 @@ final class ParameterAttributesHandler
 {
     public function __construct(
         private AttributeResolverFactoryInterface $attributeResolverFactory,
+        private ?HydratorInterface $hydrator = null,
     ) {
     }
 
@@ -60,7 +62,8 @@ public function handle(
                 );
             }
 
-            $context = new ParameterAttributeResolveContext($parameter, $resolveResult, $data);
+            $this->requireHydrator();
+            $context = new ParameterAttributeResolveContext($parameter, $resolveResult, $data, $this->hydrator);
 
             $tryResolveResult = $resolver->getParameterValue($attribute, $context);
             if ($tryResolveResult->isResolved()) {
@@ -70,4 +73,18 @@ public function handle(
 
         return $resolveResult;
     }
+
+    /**
+     * Ensure that validator is set in parameter attributes handler.
+     *
+     * @psalm-assert HydratorInterface $this->hydrator
+     *
+     * @throws RuntimeException If hydrator is not set in parameter attributes handler.
+     */
+    private function requireHydrator(): void
+    {
+        if ($this->hydrator === null) {
+            throw new RuntimeException('Hydrator is not set in parameter attributes handler.');
+        }
+    }
 }

src/Hydrator.php

@@ -56,7 +56,7 @@ public function __construct(
 
         $attributeResolverFactory ??= new ReflectionAttributeResolverFactory();
         $this->dataAttributesHandler = new DataAttributesHandler($attributeResolverFactory);
-        $this->parameterAttributesHandler = new ParameterAttributesHandler($attributeResolverFactory);
+        $this->parameterAttributesHandler = new ParameterAttributesHandler($attributeResolverFactory, $this);
 
         $this->objectFactory = $objectFactory ?? new ReflectionObjectFactory();