Added default to attribute to specify default values

Author: Fa-BRAIK

docs/PropertyAttributes.md

@@ -4,6 +4,7 @@ Property Attributes
 In order to provide more functionality to your DTOs, you can use the following attributes:
 - [Computed](#Computed) - To define a property that is computed from other properties.
 - [Aliases](#Aliases) - To define aliases for a property.
+- [DefaultsUsing](#DefaultsUsing) - To define a default value for a property using a fallback resolver.
 - [CipherTarget](#CipherTarget) - To define a property that should be encrypted/decrypted.
 
 Computed
@@ -109,3 +110,48 @@ public function __construct(
 ) {}
 ```
 
+DefaultsUsing
+-
+
+Sometimes, we may need to specify that a property has a default value, 
+we can achieve that using plain PHP for some property types but not all of them.
+
+```php
+use Nuxtifyts\PhpDto\Data;
+
+final readonly class User extends Data
+{
+    public function __construct(
+        public string $firstName,
+        public string $lastName,
+        public string $email,
+        public UserType $type = UserType::DEFAULT,
+        public UserConfigData $config,
+    ) {}
+}
+```
+
+On the other hand, if we want to specify, for example, a default value for UserType depending 
+on the provided email address, or if you want to provide a default value for complex data such as
+`UserConfigData` which is another DTO, there is no way to do it using plain PHP, 
+that's where `DefaultsUsing` attribute comes in.
+
+```php
+use Nuxtifyts\PhpDto\Data;
+use Nuxtifyts\PhpDto\Attributes\Property\DefaultsUsing;
+
+final readonly class User extends Data
+{
+    public function __construct(
+        public string $firstName,
+        public string $lastName,
+        public string $email,
+        #[DefaultsUsing(UserTypeFallbackResolver::class)]
+        public UserType $type,
+        #[DefaultsUsing(UserConfigDataFallbackResolver::class)]
+        public UserConfigData $config,
+    ) {}
+}
+```
+
+TODO - Add example of fall back resolver code

src/Attributes/Property/DefaultsTo.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Attributes\Property;
+
+use Attribute;
+use BackedEnum;
+use Nuxtifyts\PhpDto\Exceptions\FallbackResolverException;
+use Nuxtifyts\PhpDto\FallbackResolver\FallbackResolver;
+use ReflectionClass;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class DefaultsTo
+{
+    /** @var array<string, ReflectionClass<object>> */
+    protected static array $_resolverReflections = [];
+
+    /** @var ?class-string<FallbackResolver>  */
+    protected(set) ?string $fallbackResolverClass = null;
+
+    /**
+     * @throws FallbackResolverException
+     */
+    public function __construct(
+        protected(set) BackedEnum|int|string|float|bool|null $value
+    ) {
+        if (is_string($value) && class_exists($value)) {
+            /** @var ReflectionClass<object> $reflection */
+            $reflection = self::$_resolverReflections[$value] ??= new ReflectionClass($value);
+
+            if (!$reflection->implementsInterface(FallbackResolver::class)) {
+                throw FallbackResolverException::unableToFindResolverClass($value);
+            } else {
+                /** @var class-string<FallbackResolver> $value */
+                $this->fallbackResolverClass = $value;
+            }
+        }
+    }
+}

src/Concerns/BaseData.php

@@ -8,6 +8,7 @@
 use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\DecipherDataPipe;
 use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\DeserializePipelinePassable;
 use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\RefineDataPipe;
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\ResolveDefaultDataPipe;
 use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\ResolveValuesFromAliasesPipe;
 use Nuxtifyts\PhpDto\Support\Pipeline;
 use Nuxtifyts\PhpDto\Support\Traits\HasNormalizers;
@@ -26,7 +27,7 @@ final public static function from(mixed $value): static
         try {
             $value = static::normalizeValue($value, static::class);
 
-            if (empty($value)) {
+            if ($value === false) {
                 throw new DeserializeException(
                     code: DeserializeException::INVALID_VALUE_ERROR_CODE
                 );
@@ -39,6 +40,7 @@ final public static function from(mixed $value): static
                 ->through(ResolveValuesFromAliasesPipe::class)
                 ->through(RefineDataPipe::class)
                 ->through(DecipherDataPipe::class)
+                ->through(ResolveDefaultDataPipe::class)
                 ->sendThenReturn(new DeserializePipelinePassable(
                     classContext: $context,
                     data: $value

src/Contexts/PropertyContext.php

@@ -5,6 +5,7 @@
 use Nuxtifyts\PhpDto\Attributes\Property\Aliases;
 use Nuxtifyts\PhpDto\Attributes\Property\CipherTarget;
 use Nuxtifyts\PhpDto\Attributes\Property\Computed;
+use Nuxtifyts\PhpDto\Attributes\Property\DefaultsTo;
 use Nuxtifyts\PhpDto\Attributes\Property\WithRefiner;
 use Nuxtifyts\PhpDto\DataCiphers\CipherConfig;
 use Nuxtifyts\PhpDto\DataRefiners\DataRefiner;
@@ -13,6 +14,7 @@
 use Nuxtifyts\PhpDto\Exceptions\SerializeException;
 use Nuxtifyts\PhpDto\Exceptions\UnknownTypeException;
 use Nuxtifyts\PhpDto\Exceptions\UnsupportedTypeException;
+use Nuxtifyts\PhpDto\FallbackResolver\FallbackConfig;
 use Nuxtifyts\PhpDto\Serializers\Serializer;
 use Nuxtifyts\PhpDto\Support\Traits\HasSerializers;
 use Nuxtifyts\PhpDto\Support\Traits\HasTypes;
@@ -42,6 +44,8 @@ class PropertyContext
 
     private(set) ?CipherConfig $cipherConfig = null;
 
+    private(set) ?FallbackConfig $fallbackConfig = null;
+
     /** @var list<DataRefiner> */
     private(set) array $dataRefiners = [];
 
@@ -112,6 +116,16 @@ private function syncPropertyAttributes(): void
                 encoded: $instance->encoded
             );
         }
+
+        if ($defaultsToAttribute = $this->reflection->getAttributes(DefaultsTo::class)[0] ?? null) {
+            /** @var ReflectionAttribute<DefaultsTo> $defaultsToAttribute */
+            $instance = $defaultsToAttribute->newInstance();
+
+            $this->fallbackConfig = new FallbackConfig(
+                value: $instance->value,
+                resolverClass: $instance->fallbackResolverClass
+            );
+        }
     }
 
     public function getValue(object $object): mixed

src/Exceptions/FallbackResolverException.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Exceptions;
+
+use Exception;
+
+class FallbackResolverException extends Exception
+{
+    protected const int UNABLE_TO_FIND_RESOLVER_CLASS = 0;
+    protected const int UNABLE_TO_RESOLVE_DEFAULT_VALUE = 1;
+
+    public static function unableToFindResolverClass(string $resolverClass): self
+    {
+        return new self(
+            "Unable to find resolver class: {$resolverClass}",
+            self::UNABLE_TO_FIND_RESOLVER_CLASS
+        );
+    }
+
+    public static function unableToResolveDefaultValue(): self
+    {
+        return new self(
+            'Unable to resolve default value',
+            self::UNABLE_TO_RESOLVE_DEFAULT_VALUE
+        );
+    }
+}

src/FallbackResolver/FallbackConfig.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\FallbackResolver;
+
+use BackedEnum;
+
+readonly class FallbackConfig
+{
+    /**
+     * @param ?class-string<FallbackResolver> $resolverClass
+     */
+    public function __construct(
+        public BackedEnum|int|string|float|bool|null $value,
+        public ?string $resolverClass = null
+    ) {
+    }
+}

src/FallbackResolver/FallbackResolver.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\FallbackResolver;
+
+use Nuxtifyts\PhpDto\Contexts\PropertyContext;
+use Nuxtifyts\PhpDto\Exceptions\FallbackResolverException;
+
+interface FallbackResolver
+{
+    /**
+     * @param array<string, mixed> $rawData
+     *
+     * @throws FallbackResolverException
+     */
+    public static function resolve(array $rawData, PropertyContext $property): mixed;
+}

src/Normalizers/ArrayNormalizer.php

@@ -8,7 +8,10 @@ public function normalize(): array|false
     {
         if (
             !is_array($this->value)
-            || array_is_list($this->value)
+            || (
+                array_is_list($this->value)
+                && !empty($this->value)
+            )
         ) {
             return false;
         }

src/Pipelines/DeserializePipeline/ResolveDefaultDataPipe.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline;
+
+use Nuxtifyts\PhpDto\Support\Passable;
+use Nuxtifyts\PhpDto\Support\Pipe;
+
+/**
+ * @extends Pipe<DeserializePipelinePassable>
+ */
+readonly class ResolveDefaultDataPipe extends Pipe
+{
+    public function handle(Passable $passable): DeserializePipelinePassable
+    {
+        $data = $passable->data;
+
+        foreach ($passable->classContext->properties as $propertyContext) {
+            if (array_key_exists($propertyContext->propertyName, $data)) {
+                continue;
+            }
+
+            if ($propertyContext->fallbackConfig) {
+                $data[$propertyContext->propertyName] = $propertyContext->fallbackConfig->resolverClass
+                    ? $propertyContext->fallbackConfig->resolverClass::resolve($data, $propertyContext)
+                    : $propertyContext->fallbackConfig->value;
+            }
+
+            if ($propertyContext->reflection->hasDefaultValue()) {
+                $data[$propertyContext->propertyName] = $propertyContext->reflection->getDefaultValue();
+            }
+        }
+
+        return $passable->with(data: $data);
+    }
+}

src/Support/Traits/HasNormalizers.php

@@ -21,7 +21,7 @@ protected static function normalizeValue(mixed $value, string $class): array|fal
         foreach (static::allNormalizer() as $normalizer) {
             $normalized = new $normalizer($value, $class)->normalize();
 
-            if (!empty($normalized)) {
+            if ($normalized !== false) {
                 return $normalized;
             }
         }

tests/Unit/Attributes/AliasesAttributeTest.php renamed to tests/Unit/Attributes/AliasesTest.php

@@ -16,7 +16,7 @@
 #[CoversClass(ResolveValuesFromAliasesPipe::class)]
 #[CoversClass(Aliases::class)]
 #[UsesClass(PersonData::class)]
-final class AliasesAttributeTest extends UnitCase
+final class AliasesTest extends UnitCase
 {
     /**
      * @throws Throwable

tests/Unit/Attributes/DefaultsToTest.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Unit\Attributes;
+
+use Nuxtifyts\PhpDto\Attributes\Property\DefaultsTo;
+use Nuxtifyts\PhpDto\Contexts\PropertyContext;
+use Nuxtifyts\PhpDto\Data;
+use Nuxtifyts\PhpDto\Exceptions\FallbackResolverException;
+use Nuxtifyts\PhpDto\FallbackResolver\FallbackConfig;
+use Nuxtifyts\PhpDto\Tests\Dummies\UserData;
+use Nuxtifyts\PhpDto\Tests\Unit\UnitCase;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use Throwable;
+
+#[CoversClass(DefaultsTo::class)]
+#[CoversClass(FallbackResolverException::class)]
+#[CoversClass(FallbackConfig::class)]
+#[CoversClass(PropertyContext::class)]
+final class DefaultsToTest extends UnitCase
+{
+    /**
+     * @throws Throwable
+     */
+    #[Test]
+    public function should_throw_an_exception_if_the_resolver_class_does_not_implement_fallback_resolver_interface(): void
+    {
+        self::expectException(FallbackResolverException::class);
+
+        new DefaultsTo(UserData::class);
+    }
+
+    /**
+     * @param array<string, mixed> $arrayData
+     * @param array<string, mixed> $expectedSerializedData
+     *
+     * @throws Throwable
+     */
+    #[Test]
+    #[DataProvider('should_be_able_to_resolve_default_values_data_provider')]
+    public function should_be_able_to_resolve_default_values(
+        Data $object,
+        array $arrayData,
+        array $expectedSerializedData
+    ): void {
+        self::assertEquals(
+            $expectedSerializedData,
+            $object::from($arrayData)->toArray()
+        );
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public static function should_be_able_to_resolve_default_values_data_provider(): array
+    {
+        return [
+            'Resolves default scalar type value' => [
+                'object' => new readonly class ('') extends Data {
+                    public function __construct(
+                        #[DefaultsTo('John')]
+                        public string $name
+                    ) {
+                    }
+                },
+                'arrayData' => [],
+                'expectedSerializedData' => [
+                    'name' => 'John'
+                ]
+            ]
+        ];
+    }
+}