Add support for creating DTO instances using a create method

Introduces a `create` method to support default values for complex types, leveraging a new streamlined `DeserializePipeline`. Adjustments include a new `DataCreationException`, documentation updates, fallback resolver enhancements, and pipeline refactoring for better organization and maintainability.

Author: Fa-BRAIK

docs/DefaultValues.md

@@ -0,0 +1,87 @@
+Default Values
+=
+
+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 `DefaultsTo` attribute comes in.
+
+```php
+use Nuxtifyts\PhpDto\Data;
+use Nuxtifyts\PhpDto\Attributes\Property\DefaultsTo;
+
+final readonly class User extends Data
+{
+    public function __construct(
+        public string $firstName,
+        public string $lastName,
+        public string $email,
+        #[DefaultsTo(UserType::DEFAULT)]
+        public UserType $type,
+        #[DefaultsTo(UserConfigDataFallbackResolver::class)]
+        public UserConfigData $config,
+    ) {}
+}
+```
+
+The `DefaultsTo` attribute provides the ability to specify default values for complex types,
+such as DateTimes and DTOs.
+
+For more details checkout the [DefaultValues](https://github.com/nuxtifyts/php-dto/blob/main/docs/DefaultValues.md)
+guide.
+
+In this example, the `UserConfigDataFallbackResolver` would look like this:
+
+```php
+use Nuxtifyts\PhpDto\Contexts\PropertyContext;
+use Nuxtifyts\PhpDto\FallbackResolver\FallbackResolver;
+
+class UserConfigDataFallbackResolver implements FallbackResolver
+{
+    /** 
+     * @param array<string, mixed> $rawData 
+     */
+    public static function resolve(array $rawData, PropertyContext $property) : mixed{
+        $email = $rawData['email'] ?? null;
+        
+        return match(true) {
+            str_contains($email, 'example.com') => new UserConfigData(/** Admin configs */),
+            default => new UserConfigData(/** User configs */)
+        }
+    }
+}
+```
+
+>! When using `DefaultsTo` attribute, priority is given to the attribute instead of the parameter's default value.
+
+If ever needed to create a new instance of a DTO with complex default value, 
+using the constructor is no longer possible, instead, you can make use of the 
+`create` function provided by the DTO class.
+
+Using the same example above, we can create a new instance of `User` with the default value for `config`:
+
+```php
+$user = User::create(
+    firstName: 'John',
+    lastName: 'Doe',
+    email: '[email protected]'
+);
+```

docs/PropertyAttributes.md

@@ -157,27 +157,5 @@ final readonly class User extends Data
 The `DefaultsTo` attribute provides the ability to specify default values for complex types, 
 such as DateTimes and DTOs.
 
-In this example, the `UserConfigDataFallbackResolver` would look like this:
-
-```php
-use Nuxtifyts\PhpDto\Contexts\PropertyContext;
-use Nuxtifyts\PhpDto\FallbackResolver\FallbackResolver;
-
-class UserConfigDataFallbackResolver implements FallbackResolver
-{
-    /** 
-     * @param array<string, mixed> $rawData 
-     */
-    public static function resolve(array $rawData, PropertyContext $property) : mixed{
-        $email = $rawData['email'] ?? null;
-        
-        return match(true) {
-            str_contains($email, 'example.com') => new UserConfigData(/** Admin configs */),
-            default => new UserConfigData(/** User configs */)
-        }
-    }
-}
-```
-
->! When using `DefaultsTo` attribute, priority is given to the attribute instead of the parameter's default value.
-
+For more details checkout the [DefaultValues](https://github.com/nuxtifyts/php-dto/blob/main/docs/DefaultValues.md) 
+guide.

src/Concerns/BaseData.php

@@ -3,14 +3,11 @@
 namespace Nuxtifyts\PhpDto\Concerns;
 
 use Nuxtifyts\PhpDto\Contexts\ClassContext;
+use Nuxtifyts\PhpDto\Exceptions\DataCreationException;
 use Nuxtifyts\PhpDto\Exceptions\DeserializeException;
 use Nuxtifyts\PhpDto\Exceptions\SerializeException;
-use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\DecipherDataPipe;
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\DeserializePipeline;
 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;
 use ReflectionClass;
 use Throwable;
@@ -19,6 +16,40 @@ trait BaseData
 {
     use HasNormalizers;
 
+    final public static function create(mixed ...$args): static
+    {
+        if (array_any(
+            array_keys($args),
+            static fn (string|int $arg) => is_numeric($arg)
+        )) {
+            throw DataCreationException::invalidProperty();
+        }
+
+        try {
+            $value = static::normalizeValue($args, static::class);
+
+            if ($value === false) {
+                throw new DeserializeException(
+                    code: DeserializeException::INVALID_VALUE_ERROR_CODE
+                );
+            }
+
+            /** @var ClassContext<static> $context */
+            $context = ClassContext::getInstance(new ReflectionClass(static::class));
+
+            $data = DeserializePipeline::createFromArray()
+                ->sendThenReturn(new DeserializePipelinePassable(
+                    classContext: $context,
+                    data: $value
+                ))
+                ->data;
+
+            return static::instanceWithConstructorCallFrom($context, $data);
+        } catch (Throwable $e) {
+            throw DataCreationException::unableToCreateInstance(static::class, $e);
+        }
+    }
+
     /**
      * @throws DeserializeException
      */
@@ -36,11 +67,7 @@ final public static function from(mixed $value): static
             /** @var ClassContext<static> $context */
             $context = ClassContext::getInstance(new ReflectionClass(static::class));
 
-            $data = new Pipeline(DeserializePipelinePassable::class)
-                ->through(ResolveValuesFromAliasesPipe::class)
-                ->through(RefineDataPipe::class)
-                ->through(DecipherDataPipe::class)
-                ->through(ResolveDefaultDataPipe::class)
+            $data = DeserializePipeline::hydrateFromArray()
                 ->sendThenReturn(new DeserializePipelinePassable(
                     classContext: $context,
                     data: $value

src/Contracts/BaseData.php

@@ -2,12 +2,18 @@
 
 namespace Nuxtifyts\PhpDto\Contracts;
 
+use Nuxtifyts\PhpDto\Exceptions\DataCreationException;
 use Nuxtifyts\PhpDto\Exceptions\DeserializeException;
 use Nuxtifyts\PhpDto\Exceptions\SerializeException;
 use JsonSerializable;
 
 interface BaseData extends JsonSerializable
 {
+    /**
+     * @throws DataCreationException
+     */
+    public static function create(mixed ...$args): static;
+
     /**
      * @return array<string, mixed>
      *

src/Exceptions/DataCreationException.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Exceptions;
+
+use Exception;
+use Throwable;
+
+class DataCreationException extends Exception
+{
+    protected const int UNABLE_TO_CREATE_INSTANCE = 0;
+    protected const int INVALID_PROPERTY = 1;
+
+    public static function unableToCreateInstance(
+        string $class,
+        ?Throwable $previous = null
+    ): self {
+        return new self(
+            message: "Unable to create instance of class {$class}",
+            code: self::UNABLE_TO_CREATE_INSTANCE,
+            previous: $previous
+        );
+    }
+
+    public static function invalidProperty(): self
+    {
+        return new self(
+            message: 'Invalid property passed to create method',
+            code: self::INVALID_PROPERTY
+        );
+    }
+}

src/Pipelines/DeserializePipeline/DeserializePipeline.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline;
+
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes\DecipherDataPipe;
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes\RefineDataPipe;
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes\ResolveDefaultDataPipe;
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes\ResolveValuesFromAliasesPipe;
+use Nuxtifyts\PhpDto\Support\Pipeline;
+
+/**
+ * @extends Pipeline<DeserializePipelinePassable>
+ */
+class DeserializePipeline extends Pipeline
+{
+    public static function hydrateFromArray(): self
+    {
+        return new DeserializePipeline(DeserializePipelinePassable::class)
+            ->through(ResolveValuesFromAliasesPipe::class)
+            ->through(RefineDataPipe::class)
+            ->through(DecipherDataPipe::class)
+            ->through(ResolveDefaultDataPipe::class);
+    }
+
+    /**
+     * @desc Basically the same as hydrateFromArray, but without deciphering data.
+     * This is used when create a new instance using the `create` static method from `BaseData`.
+     */
+    public static function createFromArray(): self
+    {
+        return new DeserializePipeline(DeserializePipelinePassable::class)
+            ->through(ResolveValuesFromAliasesPipe::class)
+            ->through(RefineDataPipe::class)
+            ->through(ResolveDefaultDataPipe::class);
+    }
+}

src/Pipelines/DeserializePipeline/DecipherDataPipe.php renamed to src/Pipelines/DeserializePipeline/Pipes/DecipherDataPipe.php

@@ -1,7 +1,8 @@
 <?php
 
-namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline;
+namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes;
 
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\DeserializePipelinePassable;
 use Nuxtifyts\PhpDto\Support\Passable;
 use Nuxtifyts\PhpDto\Support\Pipe;
 

src/Pipelines/DeserializePipeline/RefineDataPipe.php renamed to src/Pipelines/DeserializePipeline/Pipes/RefineDataPipe.php

@@ -1,10 +1,11 @@
 <?php
 
-namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline;
+namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes;
 
+use Exception;
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\DeserializePipelinePassable;
 use Nuxtifyts\PhpDto\Support\Passable;
 use Nuxtifyts\PhpDto\Support\Pipe;
-use Exception;
 
 /**
  * @extends Pipe<DeserializePipelinePassable>

src/Pipelines/DeserializePipeline/ResolveDefaultDataPipe.php renamed to src/Pipelines/DeserializePipeline/Pipes/ResolveDefaultDataPipe.php

@@ -1,7 +1,8 @@
 <?php
 
-namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline;
+namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes;
 
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\DeserializePipelinePassable;
 use Nuxtifyts\PhpDto\Support\Passable;
 use Nuxtifyts\PhpDto\Support\Pipe;
 use ReflectionParameter;

src/Pipelines/DeserializePipeline/ResolveValuesFromAliasesPipe.php renamed to src/Pipelines/DeserializePipeline/Pipes/ResolveValuesFromAliasesPipe.php

@@ -1,7 +1,8 @@
 <?php
 
-namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline;
+namespace Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes;
 
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\DeserializePipelinePassable;
 use Nuxtifyts\PhpDto\Support\Passable;
 use Nuxtifyts\PhpDto\Support\Pipe;
 

tests/Dummies/FallbackResolvers/DummyPointsFallbackResolver.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Dummies\FallbackResolvers;
+
+use Nuxtifyts\PhpDto\Tests\Dummies\PointData;
+use Nuxtifyts\PhpDto\Contexts\PropertyContext;
+use Nuxtifyts\PhpDto\FallbackResolver\FallbackResolver;
+
+class DummyPointsFallbackResolver implements FallbackResolver
+{
+    /**
+     * @return list<PointData>
+     */
+    public static function resolve(array $rawData, PropertyContext $property): array
+    {
+        return [
+            new PointData(1, 2),
+            new PointData(3, 4),
+            new PointData(5, 6),
+        ];
+    }
+}

tests/Dummies/PointData.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Dummies;
+
+use Nuxtifyts\PhpDto\Data;
+
+final readonly class PointData extends Data
+{
+    public function __construct(
+        public float $x,
+        public float $y
+    ) {
+    }
+}

tests/Dummies/PointGroupData.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Dummies;
+
+use Nuxtifyts\PhpDto\Attributes\Property\CipherTarget;
+use Nuxtifyts\PhpDto\Attributes\Property\DefaultsTo;
+use Nuxtifyts\PhpDto\Attributes\Property\Types\ArrayOfData;
+use Nuxtifyts\PhpDto\Data;
+use Nuxtifyts\PhpDto\Tests\Dummies\FallbackResolvers\DummyPointsFallbackResolver;
+
+final readonly class PointGroupData extends Data
+{
+    /**
+     * @param array<array-key, PointData> $points
+     */
+    public function __construct(
+        #[CipherTarget]
+        public string $key,
+        #[ArrayOfData(PointData::class)]
+        #[DefaultsTo(DummyPointsFallbackResolver::class)]
+        public array $points
+    ) {
+    }
+}

tests/Unit/Attributes/AliasesTest.php

@@ -4,7 +4,7 @@
 
 use Nuxtifyts\PhpDto\Attributes\Property\Aliases;
 use Nuxtifyts\PhpDto\Contexts\PropertyContext;
-use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\ResolveValuesFromAliasesPipe;
+use Nuxtifyts\PhpDto\Pipelines\DeserializePipeline\Pipes\ResolveValuesFromAliasesPipe;
 use Nuxtifyts\PhpDto\Tests\Dummies\PersonData;
 use Nuxtifyts\PhpDto\Tests\Unit\UnitCase;
 use PHPUnit\Framework\Attributes\CoversClass;