Add ability to transformed object with correct type hint

Author: pionl

docs/content/en/index.md

@@ -311,6 +311,8 @@ $value = $data->getRequiredArrayGetter('key');
 
 ### Get SimpleXMLElement
 
+> Since v0.6.0
+
 Return SimpleXMLElement for given key. Uses `xml` transformer strategy.
 
 ```php
@@ -319,7 +321,8 @@ $xml = $data->getNullableXML('child');
 
 ### GetValue with XMLData
 
-> Throws always `NotXMLException` exception if value is not a SimpleXMLElement. XML transformer strategy is applied.
+> Since v0.6.0. Throws always `NotXMLException` exception if value is not a SimpleXMLElement. XML transformer strategy
+> is applied.
 
 Get always `GetValue` instance even if provided data is missing or if null.
 
@@ -342,7 +345,8 @@ $value = $data->getRequiredXMLGetter('key');
 
 ### GetValue XML attributes
 
-> Throws always `NotXMLException` exception if value is not a SimpleXMLElement. XML transformer strategy is applied.
+> Since v0.6.0. Throws always `NotXMLException` exception if value is not a SimpleXMLElement. XML transformer strategy
+> is applied.
 
 Wraps XML element attributes in GetValue instance (even if attributes are not set in element).
 
@@ -358,6 +362,51 @@ $attributes = $data->getXMLAttributesGetter('node');
 $attributes->getString('attributeName');
 ```
 
+### GetObject
+
+> Since v0.6.1
+
+- Allows getting object of specified type.
+- You can transform raw value to expected object by using transformers (with `GetterTransformer`)
+
+```php
+use Wrkflow\GetValue\Contracts\GetValueTransformerContract;
+use Wrkflow\GetValue\GetValue;
+use Wrkflow\GetValue\DataHolders\ArrayData;
+use Wrkflow\GetValue\Transformers\GetterTransformer;
+
+$data = new GetValue(new ArrayData([
+   'person' => ['name' => 'Marco', 'surname' => 'Polo'],
+]));
+
+class PersonEntity
+{
+    public function __construct(
+        public readonly string $firstName,
+        public readonly string $lastName,
+    ) {
+    }
+}
+
+class TestEntityTransformer implements GetValueTransformerContract
+{
+    public function transform(GetValue $value, string $key): PersonEntity
+    {
+        return new PersonEntity(
+            firstName: $value->getRequiredString('name'),
+            lastName: $value->getRequiredString('surname'),
+        );
+    }
+}
+
+$person = $this->data->getObject(
+    Person::class,
+    'person',
+    new PersonTransformer()
+);
+// PersonEntity{firstName=Marco,lastName=Polo}
+```
+
 ## Exceptions
 
 > All exceptions receive full key that was used for getting data. You can receive it by using `$exception->getKey()`

src/GetValue.php

@@ -15,6 +15,7 @@
 use Wrkflow\GetValue\Actions\ValidateAction;
 use Wrkflow\GetValue\Builders\ExceptionBuilder;
 use Wrkflow\GetValue\Contracts\ExceptionBuilderContract;
+use Wrkflow\GetValue\Contracts\GetValueTransformerContract;
 use Wrkflow\GetValue\Contracts\RuleContract;
 use Wrkflow\GetValue\Contracts\TransformerContract;
 use Wrkflow\GetValue\Contracts\TransformerStrategy;
@@ -28,6 +29,7 @@
 use Wrkflow\GetValue\Rules\NumericRule;
 use Wrkflow\GetValue\Rules\StringRule;
 use Wrkflow\GetValue\Strategies\DefaultTransformerStrategy;
+use Wrkflow\GetValue\Transformers\GetterTransformer;
 
 class GetValue
 {
@@ -503,6 +505,27 @@ public function getXMLAttributesGetter(string|array|null $key = null, ?array $tr
         return $this->makeInstance(new XMLAttributesData($attributes, $this->data->getKey($parentKey)));
     }
 
+    /**
+     * @template T of object
+     * @param class-string<T>       $expectedClass
+     *
+     * @return T|null
+     */
+    public function getObject(
+        string $expectedClass,
+        string|array $key,
+        GetValueTransformerContract $getValueTransformer
+    ): ?object {
+        $transformers = [new GetterTransformer($getValueTransformer)];
+        $result = $this->getValidatedValue(ValueType::Object, $key, transformers: $transformers);
+
+        if ($result instanceof $expectedClass) {
+            return $result;
+        }
+
+        return null;
+    }
+
     public function makeInstance(AbstractData $data): self
     {
         return new self(

tests/AbstractArrayTestCase.php

@@ -129,6 +129,9 @@ protected function setUp(): void
                 self::KeyEnumInt => 's',
             ],
             self::KeyMissingValue => ['force-non-empty'],
+            'object' => [
+                'type' => 'x',
+            ],
         ]);
         $this->data = new GetValue($this->arrayData);
     }

tests/Entities/TestEntity.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValueTests\Entities;
+
+class TestEntity
+{
+    public function __construct(
+        public readonly string $type,
+    ) {
+    }
+}

tests/GetValueArrayDataTest.php

@@ -10,6 +10,9 @@
 use Wrkflow\GetValue\Exceptions\NotSupportedDataException;
 use Wrkflow\GetValue\GetValue;
 use Wrkflow\GetValue\Strategies\DefaultTransformerStrategy;
+use Wrkflow\GetValueTests\Entities\TestEntity;
+use Wrkflow\GetValueTests\Transformers\NullTransformer;
+use Wrkflow\GetValueTests\Transformers\TestEntityTransformer;
 
 class GetValueArrayDataTest extends AbstractArrayTestCase
 {
@@ -131,6 +134,19 @@ public function testGetXMLAttributesGetterOnRootArrayData(): void
         $this->data->getXMLAttributesGetter();
     }
 
+    public function testGetObject(): void
+    {
+        $result = $this->data->getObject(TestEntity::class, 'object', new TestEntityTransformer());
+        $this->assertNotNull($result);
+        $this->assertEquals('x', $result->type);
+    }
+
+    public function testGetObjectIncorrectResult(): void
+    {
+        $result = $this->data->getObject(TestEntity::class, 'object', new NullTransformer());
+        $this->assertNull($result);
+    }
+
     protected function assertItem(
         GetValue $item,
         string $expectedName,

tests/GetValueXMLDataTest.php

@@ -11,6 +11,9 @@
 use Wrkflow\GetValue\Exceptions\MissingValueForKeyException;
 use Wrkflow\GetValue\GetValue;
 use Wrkflow\GetValue\Strategies\DefaultTransformerStrategy;
+use Wrkflow\GetValueTests\Entities\TestEntity;
+use Wrkflow\GetValueTests\Transformers\NullTransformer;
+use Wrkflow\GetValueTests\Transformers\TestEntityTransformer;
 
 class GetValueXMLDataTest extends AbstractXMLTestCase
 {
@@ -87,6 +90,19 @@ public function testGetXMLGetter(): void
         $this->assertNotNull($this->data->getXMLGetter('not_exists'));
     }
 
+    public function testGetObject(): void
+    {
+        $result = $this->data->getObject(TestEntity::class, 'object', new TestEntityTransformer());
+        $this->assertNotNull($result);
+        $this->assertEquals('x', $result->type);
+    }
+
+    public function testGetObjectIncorrectResult(): void
+    {
+        $result = $this->data->getObject(TestEntity::class, 'object', new NullTransformer());
+        $this->assertNull($result);
+    }
+
     protected function assertObject(GetValue $object): void
     {
         $this->assertEquals('x', $object->getRequiredString('type'));

tests/Transformers/NullTransformer.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValueTests\Transformers;
+
+use Wrkflow\GetValue\Contracts\GetValueTransformerContract;
+use Wrkflow\GetValue\GetValue;
+
+class NullTransformer implements GetValueTransformerContract
+{
+    public function transform(GetValue $value, string $key): mixed
+    {
+        return null;
+    }
+}

tests/Transformers/TestEntityTransformer.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Wrkflow\GetValueTests\Transformers;
+
+use Wrkflow\GetValue\Contracts\GetValueTransformerContract;
+use Wrkflow\GetValue\GetValue;
+use Wrkflow\GetValueTests\Entities\TestEntity;
+
+class TestEntityTransformer implements GetValueTransformerContract
+{
+    public function transform(GetValue $value, string $key): TestEntity
+    {
+        return new TestEntity($value->getRequiredString('type'));
+    }
+}