Add Cloneable Data feature with documentation and tests

Introduced the Cloneable Data feature to allow `Data` objects to support cloning with updated values using the `with` method. Added documentation, unit tests, examples, and updated related components to reflect this enhancement.

Author: Fa-BRAIK

docs/CloneableData.md

@@ -0,0 +1,91 @@
+Cloneable Data
+= 
+
+Sometimes we may want to alter the data of a `Data` object (Partially or completely).
+And since `Data` objects are immutable by default, we can't change the data directly.
+
+To solve this, we can use the `with` function that will return a new instance of the `Data` object with the new data.
+Let take the `TodoData` class as an example:
+
+```php
+use Nuxtifyts\PhpDto\Data;
+use DateTimeImmutable;
+
+final readonly class TodoData extends Data
+{
+    public function __construct(
+        public string $title,
+        public string $content,
+        public Status $status,
+        public ?DateTimeImmutable $dueDate
+    ) {}
+}
+```
+
+The `Status` enum is defined as follows:
+
+```php
+enum Status: string
+{
+    case DEFAULT = 'default';
+    case IN_PROGRESS = 'in_progress';
+    case DONE = 'done';
+}
+```
+
+Using `with` function, we can easily create new instances of the `TodoData` class with the new data:
+
+```php
+$emptyTodo = Todo::empty();
+
+// ...
+ 
+$todo = $emptyTodo->with(
+    title: 'Learn PHP DTO',
+    content: 'Learn how to use PHP DTO',
+    status: Status::IN_PROGRESS
+);
+
+// ...
+
+$todoWithDueDate = $todo->with(
+    dueDate: new DateTimeImmutable('2025-01-06')
+);
+```
+
+> We are using the `empty` method 
+> from [Empty Data](https://github.com/nuxtifyts/php-dto/blob/main/docs/EmptyData.md)
+> here
+
+> `emptyTodo`, `todo` and `todoWithDueDate` are all different instances.
+
+Computed properties
+-
+
+When cloning a `Data` object, computed properties are automatically updated with the new data.
+
+```php
+use Nuxtifyts\PhpDto\Data;
+use Nuxtifyts\PhpDto\Attributes\Property\Computed;
+
+final readonly class PersonData extends Data
+{
+    #[Computed]
+    public string $fullName;
+    
+    public function __construct(
+        public string $firstName,
+        public string $lastName
+    ) {}
+}
+```
+
+For example: 
+
+```php
+$johnDoe = new PersonData(firstName: 'John', lastName: 'Doe');
+
+$janeDoe = $johnDoe->with(firstName: 'Jane');
+
+$janeDoe->fullName; // 'Jane Doe'
+```

docs/EmptyData.md

@@ -36,6 +36,8 @@ By calling the `empty()` method, we can create a new instance of the `Todo` clas
 $emptyTodo = Todo::empty();
 ```
 
+> This is really useful with [Cloneable Data](https://github.com/nuxtifyts/php-dto/blob/main/docs/CloneableData.md)
+
 The `$emptyTodo` variable will contain the following data:
 
 ```

docs/Quickstart.md

@@ -81,3 +81,4 @@ can be found here:
 - [Property Attributes](https://github.com/nuxtifyts/php-dto/blob/main/docs/PropertyAttributes.md)
 - [Data Refiners](https://github.com/nuxtifyts/php-dto/blob/main/docs/DataRefiners.md)
 - [Empty Data](https://github.com/nuxtifyts/php-dto/blob/main/docs/EmptyData.md)
+- [Cloneable Data](https://github.com/nuxtifyts/php-dto/blob/main/docs/CloneableData.md)

src/Concerns/CloneableData.php

@@ -20,6 +20,10 @@ public function with(mixed ...$args): static
         try {
             $value = static::normalizeValue($args, static::class);
 
+            if ($value === false) {
+                throw DataCreationException::invalidParamsPassed(static::class);
+            }
+
             /** @var ClassContext<static> $context */
             $context = ClassContext::getInstance(new ReflectionClass(static::class));
 
@@ -46,7 +50,7 @@ protected function cloneInstanceWithConstructorCall(ClassContext $context, array
             $propertyContext = $context->properties[$paramName] ?? null;
 
             if (!$propertyContext) {
-                DataCreationException::invalidProperty();
+                throw DataCreationException::invalidProperty();
             }
 
             $args[$paramName] = array_key_exists($propertyContext->propertyName, $value)

src/Exceptions/DataCreationException.php

@@ -11,6 +11,7 @@ class DataCreationException extends Exception
     protected const int INVALID_PROPERTY = 1;
     protected const int UNABLE_TO_CREATE_EMPTY_INSTANCE = 2;
     protected const int UNABLE_TO_CLONE_INSTANCE_WITH_NEW_DATA = 3;
+    protected const int INVALID_PARAMS_PASSED = 4;
 
     public static function unableToCreateInstance(
         string $class,
@@ -52,4 +53,15 @@ public static function unableToCloneInstanceWithNewData(
             previous: $previous
         );
     }
+
+    public static function invalidParamsPassed(
+        string $class,
+        ?Throwable $previous = null
+    ): self {
+        return new self(
+            message: "Invalid params passed to create method of class {$class}",
+            code: self::INVALID_PARAMS_PASSED,
+            previous: $previous
+        );
+    }
 }

tests/Dummies/DocsDummies/Todo.php renamed to tests/Dummies/DocsDummies/TodoData.php

@@ -8,7 +8,7 @@
 use Nuxtifyts\PhpDto\Tests\Dummies\Enums\Todo\Status;
 use Nuxtifyts\PhpDto\Tests\Dummies\Normalizers\GoalTodoNormalizer;
 
-final readonly class Todo extends Data
+final readonly class TodoData extends Data
 {
     public function __construct(
         public string $title,

tests/Unit/Concerns/CloneableDataTest.php

@@ -40,6 +40,19 @@ public function will_throw_an_exception_if_invalid_value_for_property_is_passed(
         $person->with(firstName: new DateTimeImmutable());
     }
 
+    /**
+     * @throws Throwable
+     */
+    #[Test]
+    public function will_throw_an_exception_if_invalid_arguments_are_passed_using_with_function(): void
+    {
+        $person = new PersonData(firstName: 'John', lastName: 'Doe');
+
+        self::expectException(DataCreationException::class);
+
+        $person->with('{firstName: "Jane"');
+    }
+
     /**
      * @throws Throwable
      */

tests/Unit/Documentation/CloneableDataExampleTest.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Unit\Documentation;
+
+use Nuxtifyts\PhpDto\Tests\Dummies\DocsDummies\TodoData;
+use Nuxtifyts\PhpDto\Tests\Dummies\PersonData;
+use Nuxtifyts\PhpDto\Tests\Unit\UnitCase;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\Attributes\Test;
+use Nuxtifyts\PhpDto\Tests\Dummies\Enums\Todo\Status;
+use DateTimeImmutable;
+use Throwable;
+
+#[UsesClass(TodoData::class)]
+#[UsesClass(PersonData::class)]
+final class CloneableDataExampleTest extends UnitCase
+{
+    /**
+     * @throws Throwable
+     */
+    #[Test]
+    public function test_it_can_clone_data_as_example_in_documentation(): void
+    {
+        $emptyTodo = TodoData::empty();
+
+        self::assertEquals([
+            'title' => '',
+            'content' => '',
+            'status' => Status::BACKLOG->value,
+            'dueDate' => null
+        ], $emptyTodo->toArray());
+
+        $todo = $emptyTodo->with(
+            title: 'Learn PHP DTO',
+            content: 'Learn how to use PHP DTO',
+            status: Status::IN_PROGRESS
+        );
+
+        self::assertEquals([
+            'title' => 'Learn PHP DTO',
+            'content' => 'Learn how to use PHP DTO',
+            'status' => Status::IN_PROGRESS->value,
+            'dueDate' => null
+        ], $todo->toArray());
+
+        $dueDate = new DateTimeImmutable('2021-10-10');
+        $todoWithDueDate = $todo->with(dueDate: $dueDate);
+
+        self::assertEquals(
+            $dueDate->format('Y-m-d H:i'),
+            $todoWithDueDate->dueDate?->format('Y-m-d H:i')
+        );
+    }
+
+    /**
+     * @throws Throwable
+     */
+    #[Test]
+    public function test_is_can_clone_dts_with_computed_properties(): void
+    {
+        $person = new PersonData(firstName: 'John', lastName: 'Doe');
+
+        self::assertEquals('John Doe', $person->fullName);
+
+        $personWithFirstName = $person->with(firstName: 'Jane');
+
+        self::assertEquals('Jane Doe', $personWithFirstName->fullName);
+    }
+}

tests/Unit/Documentation/NormalizersExampleTest.php

@@ -6,13 +6,13 @@
 use Nuxtifyts\PhpDto\Tests\Unit\UnitCase;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
-use Nuxtifyts\PhpDto\Tests\Dummies\DocsDummies\Todo;
+use Nuxtifyts\PhpDto\Tests\Dummies\DocsDummies\TodoData;
 use Nuxtifyts\PhpDto\Tests\Dummies\DocsDummies\NonData\Goal;
 use DateTimeImmutable;
 use DateTimeInterface;
 use Throwable;
 
-#[UsesClass(Todo::class)]
+#[UsesClass(TodoData::class)]
 #[UsesClass(Goal::class)]
 final class NormalizersExampleTest extends UnitCase
 {
@@ -30,7 +30,7 @@ public function will_be_able_to_normalize_instance_of_goal_class_to_todo_class()
             dueDate: $now
         );
 
-        $todo = Todo::from($goal);
+        $todo = TodoData::from($goal);
 
         self::assertEquals(
             [

tests/Unit/Documentation/QuickStartExampleTest.php

@@ -2,7 +2,7 @@
 
 namespace Nuxtifyts\PhpDto\Tests\Unit\Documentation;
 
-use Nuxtifyts\PhpDto\Tests\Dummies\DocsDummies\Todo;
+use Nuxtifyts\PhpDto\Tests\Dummies\DocsDummies\TodoData;
 use Nuxtifyts\PhpDto\Tests\Unit\UnitCase;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -11,7 +11,7 @@
 use DateTimeInterface;
 use Throwable;
 
-#[UsesClass(Todo::class)]
+#[UsesClass(TodoData::class)]
 final class QuickStartExampleTest extends UnitCase
 {
     /**
@@ -29,14 +29,14 @@ public function will_perform_serialize_and_deserialize_on_data_transfer_objects_
             'dueDate' => $now->format(DateTimeInterface::ATOM)
         ];
 
-        $todo = new Todo(
+        $todo = new TodoData(
             title: 'Learn PHP DTO',
             content: 'Learn how to use PHP DTO',
             status: Status::READY,
             dueDate: $now
         );
 
-        $todoFrom = Todo::from([
+        $todoFrom = TodoData::from([
             'title' => 'Learn PHP DTO',
             'content' => 'Learn how to use PHP DTO',
             'status' => 'ready',