[2.1] Add factory interface to support self initialized nullable value objects (#15)

* feat  add value object factory interface to support nullable value objects in the resource
* refactor: handle objects without attributes as empty array
* feat: add ValueObjectFactoryTrait
* feat: empty resource value arrays initialize value objects
* fix: Fix a bug where uninitialized value objects are treated like valid instances, although they should be null (#17)

Author: chris-doehring

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v2.1.0 - 2021-07-29
+
+- Add support for self initialized nullable value objects
+- Model converter: Empty value objects are now converted to empty hashes
+- Model converter: Fix a bug where uninitialized value objects are treated like valid instances, although they should be `null`
+
 ## v2.0.0 - 2021-07-11
 
 - Dropped `doctrine/annotations` support. All JSON API model declarations must be php 8 attributes.

docs/08-models.md

@@ -93,9 +93,12 @@ class User implements CustomAttributeGetterInterface, CustomAttributeSetterInter
 }
 ```
 
-The model conversion supports the filling and conversion of all types of member properties. This also includes object properties, under two conditions:
-* the value object also contains `Attribute` properties (`Id` and `Type` is only supported on root level)
-* when converting from JSON API resource to model, the object property has to be an initialized object instance
+The model conversion supports the filling and conversion of all types of member properties. This also applies to object properties.
+However, there are some points to consider here:
+* the value object should contain `Attribute` properties, although it's not required (`Id` and `Type` is only supported on root level)
+* when converting from JSON API resource to model the object property has to be an initialized object instance OR
+must implement the `\Dogado\JsonApi\Support\Model\ValueObjectFactoryInterface` when it's nullable.  Feel free to use the
+`ValueObjectFactoryTrait` which contains a simple `create` factory method.
 
 Whenever you want to use objects as JSON API attributes which do not hold attribute definitions themselves, you have to use either the `CustomAttributeGetterInterface` or `CustomAttributeSetterInterface`, depending on your needs.
 

src/Converter/ResourceConverter.php

@@ -8,6 +8,7 @@
 use Dogado\JsonApi\Model\Resource\ResourceInterface;
 use Dogado\JsonApi\Support\Model\CustomAttributeSetterInterface;
 use Dogado\JsonApi\Support\Model\DataModelAnalyser;
+use Dogado\JsonApi\Support\Model\ValueObjectFactoryInterface;
 use ReflectionClass;
 use ReflectionException;
 use ReflectionNamedType;
@@ -66,7 +67,7 @@ public function toModel(?ResourceInterface $resource, object $model): object
     protected function setValue(ReflectionClass $reflection, object $model, array $propertyMap, mixed $value): void
     {
         $propertyName = array_shift($propertyMap);
-        if (!$reflection->hasProperty($propertyName)) {
+        if (null === $propertyName || !$reflection->hasProperty($propertyName)) {
             return;
         }
 
@@ -78,34 +79,48 @@ protected function setValue(ReflectionClass $reflection, object $model, array $p
         }
 
         $property = $reflection->getProperty($propertyName);
-        if (null !== $property->getType() && !$property->getType() instanceof ReflectionNamedType) {
+        $propertyType = $property->getType();
+        if (null !== $propertyType && !$propertyType instanceof ReflectionNamedType) {
             // other reflection types, like union types, are not supported
             return;
         }
 
         if (
-            null === $property->getType() ||
-            'mixed' === $property->getType()->getName() ||
-            $property->getType()->getName() === gettype($value)
+            null === $propertyType ||
+            'mixed' === $propertyType->getName() ||
+            $propertyType->getName() === gettype($value)
         ) {
             $property->setAccessible(true);
             $property->setValue($model, $value);
             return;
         }
 
-        if (class_exists($property->getType()->getName()) && 0 < count($propertyMap)) {
+        $propertyClassName = $propertyType->getName();
+        if (class_exists($propertyClassName)) {
+            if (null === $value) {
+                return;
+            }
+
             $property->setAccessible(true);
             $valueObject = $property->getValue($model);
             if (null === $valueObject) {
-                return;
+                if (
+                    !(new ReflectionClass($propertyClassName))
+                        ->implementsInterface(ValueObjectFactoryInterface::class)
+                ) {
+                    return;
+                }
+                /** @var ValueObjectFactoryInterface $propertyClassName */
+                $valueObject = $propertyClassName::create();
+                $property->setValue($model, $valueObject);
             }
 
             $this->setValue(new ReflectionClass($valueObject), $valueObject, $propertyMap, $value);
             return;
         }
 
         if (null === $value) {
-            if (!$property->getType()->allowsNull()) {
+            if (!$propertyType->allowsNull()) {
                 throw DataModelSerializerException::propertyIsNotNullable(
                     $this->resource ? $this->resource->type() : 'unknown',
                     get_class($model),
@@ -122,7 +137,7 @@ protected function setValue(ReflectionClass $reflection, object $model, array $p
             return;
         }
 
-        switch ($property->getType()->getName()) {
+        switch ($propertyType->getName()) {
             case 'boolean':
             case 'bool':
                 $property->setAccessible(true);

src/Support/Model/DataModelAnalyser.php

@@ -188,12 +188,20 @@ protected function parseValueObject(
         // In case the value object has no attributes, we must register the attribute prefix with a null value.
         $this->propertyMap['attributes'] = array_merge(
             $this->propertyMap['attributes'],
-            $self->getAttributesPropertyMap() ?: [$attributePrefix => $propertyPrefix]
-        );
-        $this->resourceValueMap['attributes'] = array_merge(
-            $this->resourceValueMap['attributes'],
-            $self->getAttributeValues() ?: [$attributePrefix => null]
+            [$attributePrefix => $propertyPrefix],
+            $self->getAttributesPropertyMap(),
         );
+        if (null === $valueObject) {
+            $this->resourceValueMap['attributes'] = array_merge(
+                $this->resourceValueMap['attributes'],
+                [$attributePrefix => null]
+            );
+        } else {
+            $this->resourceValueMap['attributes'] = array_merge(
+                $this->resourceValueMap['attributes'],
+                $self->getAttributeValues() ?: [$attributePrefix => []]
+            );
+        }
     }
 
     private function registerAttributeValue(

src/Support/Model/ValueObjectFactoryInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dogado\JsonApi\Support\Model;
+
+interface ValueObjectFactoryInterface
+{
+    public static function create(): self;
+}

src/Support/Model/ValueObjectFactoryTrait.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dogado\JsonApi\Support\Model;
+
+trait ValueObjectFactoryTrait
+{
+    public static function create(): self
+    {
+        return new self();
+    }
+}

tests/Converter/ModelConverterTest.php

@@ -30,9 +30,8 @@ public function testModelToResource(): void
             'values' => [
                 'number' => $model->getValueObject()->getTest(),
             ],
-            'empty-values' => [
-                'number' => null,
-            ],
+            'empty-values' => null,
+            'valueObjectWithoutAttributes' => [],
             'createdAt' => $date->format(DateTimeInterface::ATOM),
             'updatedAt' => null,
         ]);

tests/Converter/ModelConverterTest/DataModel.php

@@ -26,6 +26,9 @@ class DataModel implements CustomAttributeGetterInterface, CustomAttributeSetter
     #[Attribute('empty-values')]
     private ?ValueObject $valueObjectNotInitialized = null;
 
+    #[Attribute]
+    private ValueObjectWithoutAttributes $valueObjectWithoutAttributes;
+
     #[Attribute(ignoreOnNull: true)]
     private ?string $ignoreOnNull = null;
 
@@ -39,6 +42,7 @@ public function __construct(DateTime $createdAt)
     {
         $this->createdAt = $createdAt;
         $this->valueObject = new ValueObject();
+        $this->valueObjectWithoutAttributes = new ValueObjectWithoutAttributes();
     }
 
     public function __getAttribute(string $property): ?string

tests/Converter/ModelConverterTest/ValueObjectWithoutAttributes.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Dogado\JsonApi\Tests\Converter\ModelConverterTest;
+
+class ValueObjectWithoutAttributes
+{
+    private ?int $someProperty = 1213435664;
+}

tests/Converter/ResourceConverterTest.php

@@ -8,6 +8,8 @@
 use Dogado\JsonApi\Model\Resource\Resource;
 use Dogado\JsonApi\Tests\Converter\ResourceConverterTest\DataModel;
 use Dogado\JsonApi\Tests\Converter\ResourceConverterTest\DataModelWithoutTypeAnnotation;
+use Dogado\JsonApi\Tests\Converter\ResourceConverterTest\ValueObjectWithFactory;
+use Dogado\JsonApi\Tests\Converter\ResourceConverterTest\ValueObjectWithFactoryWrapper;
 use Dogado\JsonApi\Tests\TestCase;
 use ReflectionException;
 use stdClass;
@@ -41,6 +43,9 @@ public function testResourceToModel(): void
                     'number' => (string) $this->faker()->numberBetween(),
                     'ignoreOnNull' => $this->faker()->text(),
                 ],
+                'nullableValueObject' => [
+                    'item' => $this->faker()->numberBetween(),
+                ],
                 'arrayItems' => [
                     $this->faker->slug() => $this->faker->text(),
                     $this->faker->slug() => $this->faker->text(),
@@ -82,6 +87,11 @@ public function testResourceToModel(): void
             $attributes->getSubCollection('values')->getRequired('ignoreOnNull'),
             $model->getValueObject()->getIgnoreOnNull()
         );
+        $this->assertNotNull($model->getNullableValueObject());
+        $this->assertEquals(
+            (int) $attributes->getSubCollection('nullableValueObject')->getRequired('item'),
+            $model->getNullableValueObject()->getItem()
+        );
         $this->assertEquals(
             $attributes->get('arrayItems'),
             $model->getArrayItems()
@@ -168,4 +178,62 @@ public function testNullableResourceWithInvalidModel(): void
         $this->expectExceptionObject(DataModelSerializerException::typeAnnotationMissing(stdClass::class));
         (new ResourceConverter())->toModel(null, new stdClass());
     }
+
+    public function testNullableValueObject(): void
+    {
+        $resource = new Resource('dummy-deserializer-model', (string) $this->faker()->numberBetween(), [
+            'notNullable' => $this->faker()->slug(),
+            'createdAt' => $this->faker()->dateTime()->format(DateTimeInterface::ATOM),
+        ]);
+
+        $model = new DataModel();
+        (new ResourceConverter())->toModel($resource, $model);
+        $this->assertNull($model->getNullableValueObject());
+    }
+
+    public function testEmptyArraysInitializeNullableValueObjects(): void
+    {
+        $resource = new Resource('dummy-deserializer-model', (string) $this->faker()->numberBetween(), [
+            'notNullable' => $this->faker()->slug(),
+            'createdAt' => $this->faker()->dateTime()->format(DateTimeInterface::ATOM),
+            'nullableValueObject' => [],
+        ]);
+
+        $model = new DataModel();
+        (new ResourceConverter())->toModel($resource, $model);
+        $this->assertInstanceOf(ValueObjectWithFactory::class, $model->getNullableValueObject());
+        $this->assertNull($model->getNested());
+    }
+
+    public function testNestedEmptyArraysInitializeNullableValueObjects(): void
+    {
+        $resource = new Resource('dummy-deserializer-model', (string) $this->faker()->numberBetween(), [
+            'notNullable' => $this->faker()->slug(),
+            'createdAt' => $this->faker()->dateTime()->format(DateTimeInterface::ATOM),
+            'nested' => [
+                'nullableValueObject' => [],
+            ],
+        ]);
+
+        $model = new DataModel();
+        (new ResourceConverter())->toModel($resource, $model);
+        $this->assertInstanceOf(ValueObjectWithFactoryWrapper::class, $model->getNested());
+        $this->assertInstanceOf(ValueObjectWithFactory::class, $model->getNested()->getNullableValueObject());
+    }
+
+    public function testNestedMissingValueDoesNotInitializeValueObjects(): void
+    {
+        $resource = new Resource('dummy-deserializer-model', (string) $this->faker()->numberBetween(), [
+            'notNullable' => $this->faker()->slug(),
+            'createdAt' => $this->faker()->dateTime()->format(DateTimeInterface::ATOM),
+            'nested' => [
+                'nullableValueObject' => null,
+            ],
+        ]);
+
+        $model = new DataModel();
+        (new ResourceConverter())->toModel($resource, $model);
+        $this->assertInstanceOf(ValueObjectWithFactoryWrapper::class, $model->getNested());
+        $this->assertNull($model->getNested()->getNullableValueObject());
+    }
 }

tests/Converter/ResourceConverterTest/DataModel.php

@@ -40,6 +40,12 @@ class DataModel implements CustomAttributeSetterInterface
     #[Attribute('values')]
     private ValueObject $valueObject;
 
+    #[Attribute]
+    private ?ValueObjectWithFactory $nullableValueObject = null;
+
+    #[Attribute]
+    private ?ValueObjectWithFactoryWrapper $nested = null;
+
     #[Attribute('arrayItems')]
     private ?array $arrayItems = null;
 
@@ -138,6 +144,16 @@ public function getValueObject(): ValueObject
         return $this->valueObject;
     }
 
+    public function getNullableValueObject(): ?ValueObjectWithFactory
+    {
+        return $this->nullableValueObject;
+    }
+
+    public function getNested(): ?ValueObjectWithFactoryWrapper
+    {
+        return $this->nested;
+    }
+
     public function getArrayItems(): ?array
     {
         return $this->arrayItems;

tests/Converter/ResourceConverterTest/ValueObjectWithFactory.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Dogado\JsonApi\Tests\Converter\ResourceConverterTest;
+
+use Dogado\JsonApi\Attribute\Attribute;
+use Dogado\JsonApi\Support\Model\ValueObjectFactoryInterface;
+use Dogado\JsonApi\Support\Model\ValueObjectFactoryTrait;
+
+class ValueObjectWithFactory implements ValueObjectFactoryInterface
+{
+    use ValueObjectFactoryTrait;
+
+    #[Attribute]
+    private ?int $item = null;
+
+    public function getItem(): ?int
+    {
+        return $this->item;
+    }
+}

tests/Converter/ResourceConverterTest/ValueObjectWithFactoryWrapper.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Dogado\JsonApi\Tests\Converter\ResourceConverterTest;
+
+use Dogado\JsonApi\Attribute\Attribute;
+use Dogado\JsonApi\Support\Model\ValueObjectFactoryInterface;
+use Dogado\JsonApi\Support\Model\ValueObjectFactoryTrait;
+
+class ValueObjectWithFactoryWrapper implements ValueObjectFactoryInterface
+{
+    use ValueObjectFactoryTrait;
+
+    #[Attribute]
+    private ?ValueObjectWithFactory $nullableValueObject = null;
+
+    public function getNullableValueObject(): ?ValueObjectWithFactory
+    {
+        return $this->nullableValueObject;
+    }
+}