Enhance with method to support multiple input formats.

Added support for cloning `Data` instances using JSON, `stdClass`, and other normalized formats. Updated tests and documentation to reflect the changes, and ensured the method throws an exception when no parameters are passed.

Author: Fa-BRAIK

docs/CloneableData.md

@@ -89,3 +89,31 @@ $janeDoe = $johnDoe->with(firstName: 'Jane');
 
 $janeDoe->fullName; // 'Jane Doe'
 ```
+
+Normalizers
+-
+
+When cloning a `Data` object, normalizers that are typically used when hydrating a `Data` object
+using `from` method are also used.
+
+This will allow the ability to pass `json` data, `ArrayAccess` or `stdClass` objects for example to the `with` method.
+If a custom normalizer is implemented for the `Data` class, it can be used as well.
+
+```php
+$johnDoe = new PersonDaa('John', 'Doe');
+
+$janeDoe = $johnDoe->with('{"firstName": "Jane"}');
+
+$janeDoe->fullName; // 'Jane Doe'
+```
+
+Using an `stdClass` object:
+
+```php
+$object = new stdClass();
+$object->firstName = 'Jake';
+
+$jakeDoe = $janeDoe->with($object);
+
+$jakeDoe->fullName; // 'Jake Doe'
+```

src/Concerns/CloneableData.php

@@ -18,7 +18,12 @@ trait CloneableData
     public function with(mixed ...$args): static
     {
         try {
-            $value = static::normalizeValue($args, static::class);
+            if (empty($args)) {
+                throw DataCreationException::invalidParamsPassed(static::class);
+            }
+
+            $value = static::normalizeValue($args, static::class)
+                ?: static::normalizeValue($args[0], static::class);
 
             if ($value === false) {
                 throw DataCreationException::invalidParamsPassed(static::class);

tests/Unit/Concerns/CloneableDataTest.php

@@ -77,6 +77,19 @@ public function __construct(
         $object->with(lastName: 'Doe');
     }
 
+    /**
+     * @throws Throwable
+     */
+    #[Test]
+    public function will_throw_an_exception_if_no_param_is_passed(): void
+    {
+        $person = new PersonData(firstName: 'John', lastName: 'Doe');
+
+        self::expectException(DataCreationException::class);
+
+        $person->with();
+    }
+
     /**
      * @param array<string, mixed> $args
      * @param array<string, mixed> $expectedProperties

tests/Unit/Documentation/CloneableDataExampleTest.php

@@ -8,6 +8,7 @@
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\Attributes\Test;
 use Nuxtifyts\PhpDto\Tests\Dummies\Enums\Todo\Status;
+use stdClass;
 use DateTimeImmutable;
 use Throwable;
 
@@ -19,7 +20,7 @@ final class CloneableDataExampleTest extends UnitCase
      * @throws Throwable
      */
     #[Test]
-    public function test_it_can_clone_data_as_example_in_documentation(): void
+    public function it_can_clone_data_as_example_in_documentation(): void
     {
         $emptyTodo = TodoData::empty();
 
@@ -56,7 +57,7 @@ public function test_it_can_clone_data_as_example_in_documentation(): void
      * @throws Throwable
      */
     #[Test]
-    public function test_is_can_clone_dts_with_computed_properties(): void
+    public function it_can_clone_data_instances_with_computed_properties(): void
     {
         $person = new PersonData(firstName: 'John', lastName: 'Doe');
 
@@ -66,4 +67,33 @@ public function test_is_can_clone_dts_with_computed_properties(): void
 
         self::assertEquals('Jane Doe', $personWithFirstName->fullName);
     }
+
+    /**
+     * @throws Throwable
+     */
+    #[Test]
+    public function it_can_clone_data_instances_by_passing_json(): void
+    {
+        $person = new PersonData(firstName: 'John', lastName: 'Doe');
+
+        $personWithFirstName = $person->with('{"firstName": "Jane"}');
+
+        self::assertEquals('Jane Doe', $personWithFirstName->fullName);
+    }
+
+    /**
+     * @throws Throwable
+     */
+    #[Test]
+    public function it_can_clone_data_instances_by_passing_std_object(): void
+    {
+        $person = new PersonData(firstName: 'John', lastName: 'Doe');
+
+        $object = new stdClass();
+        $object->firstName = 'Jane';
+
+        $personWithFirstName = $person->with($object);
+
+        self::assertEquals('Jane Doe', $personWithFirstName->fullName);
+    }
 }