Adjusted documentation

Author: Fa-BRAIK

README.md

@@ -27,6 +27,32 @@ final readonly class UserData extends Data
 }
 ```
 
+You can then create an instance of the class from a mixed value. The DTO will then attempt to hydrate the object with the given data.
+
+```php
+$data = [
+    'firstName' => 'John',
+    'lastName' => 'Doe',
+    'fullName' => 'John Doe'
+];
+
+$user = UserData::from($data);
+```
+
+DTOs can also be serialized to an array:
+
+```php
+
+$user = new UserData('John', 'Doe');
+
+$userData = $user->toArray();
+
+// Or you can use the json_encode function, as the DTO implements the JsonSerializable interface
+
+$userData = json_encode($user);
+
+```
+
 ### Note
 
 This package was inspired from the [spatie/data-transfer-object](https://github.com/spatie/laravel-data) package.
@@ -41,5 +67,3 @@ and if you are using Laravel, I highly recommend using the original package. ins
 
 - PHP 8.4 or higher
 - That's it!
-
-

src/Concerns/BaseData.php

@@ -112,4 +112,14 @@ final public function jsonSerialize(): array
             throw new SerializeException($e->getMessage(), $e->getCode(), $e);
         }
     }
+
+    /**
+     * @return array<string, mixed>
+     *
+     * @throws SerializeException
+     */
+    final public function toArray(): array
+    {
+        return $this->jsonSerialize();
+    }
 }

tests/Dummies/ArrayOfMixedAttributesData.php

@@ -10,6 +10,9 @@
 
 final readonly class ArrayOfMixedAttributesData extends Data
 {
+    /**
+     * @param ?array<array-key, int|YesNoBackedEnum>  $arrayOfIntegersOrBackedEnums
+     */
     public function __construct(
         #[ArrayOfScalarTypes(Type::INT)]
         #[ArrayOfBackedEnums(YesNoBackedEnum::class)]

tests/Dummies/DocsDummies/UserDetailsData.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Dummies\DocsDummies;
+
+use Nuxtifyts\PhpDto\Data;
+
+final readonly class UserDetailsData extends Data
+{
+    public string $fullName;
+
+    public function __construct(
+        public string $firstName,
+        public string $lastName
+    ) {
+        $this->fullName = $this->firstName . ' ' . $this->lastName;
+    }
+}

tests/Unit/Documentation/ReadmeExampleTest.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Nuxtifyts\PhpDto\Tests\Unit\Documentation;
+
+use Nuxtifyts\PhpDto\Data;
+use Nuxtifyts\PhpDto\Tests\Dummies\DocsDummies\UserDetailsData;
+use Nuxtifyts\PhpDto\Tests\Unit\UnitCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\UsesClass;
+use Throwable;
+
+#[UsesClass(UserDetailsData::class)]
+final class ReadmeExampleTest extends UnitCase
+{
+    /**
+     * @param class-string<Data> $dtoClass
+     * @param array<string, mixed> $data
+     * @param array<string, mixed> $expectedDtoProperties
+     * @param array<string, mixed> $expectedSerializedProperties
+     *
+     * @throws Throwable
+     */
+    #[Test]
+    #[DataProvider('data_provider')]
+    public function will_perform_serialize_and_deserialize_on_data_transfer_objects_from_docs(
+        string $dtoClass,
+        array $data,
+        array $expectedDtoProperties,
+        array $expectedSerializedProperties,
+    ): void {
+        $dtoObject = $dtoClass::from($data);
+
+        foreach ($expectedDtoProperties as $property => $value) {
+            self::assertEquals($value, $dtoObject->{$property});
+        }
+
+        self::assertEquals(
+            $expectedSerializedProperties,
+            $dtoObject->jsonSerialize()
+        );
+    }
+
+    /**
+     * @return array<string, array{
+     *     dtoClass: class-string<Data>,
+     *     data: array<string, mixed>,
+     *     expectedDtoProperties: array<string, mixed>,
+     *     expectedSerializedProperties: array<string, mixed>
+     * }>
+     */
+    public static function basic_examples_data_provider(): array
+    {
+        // @phpstan-ignore-next-line
+        return [
+            'First basic example' => [
+                'dtoClass' => UserDetailsData::class,
+                'data' => $data = [
+                    'firstName' => 'John',
+                    'lastName' => 'Doe',
+                    'fullName' => 'John Doe'
+                ],
+                'expectedDtoProperties' => [
+                    'firstName' => 'John',
+                    'lastName' => 'Doe',
+                    'fullName' => 'John Doe'
+                ],
+                'expectedSerializedProperties' => $data
+            ]
+        ];
+    }
+}

tests/Unit/Serializers/ArraySerializerTest.php

@@ -157,6 +157,25 @@ public static function will_perform_data_serialization_on_array_types_data_provi
                 ],
                 'propertyName' => 'arrayOfIntegersOrBackedEnums',
                 'expectedDeserializedValue' => [YesNoBackedEnum::YES, YesNoBackedEnum::NO]
+            ],
+            'Associated array of data' => [
+                'object' => new ArrayOfAttributesData(
+                    arrayOfPersonData: [
+                        'john-doe' => new PersonData('John', 'Doe'),
+                        'jane-doe' => new PersonData('Jane', 'Doe'),
+                    ]
+                ),
+                'expectedSerializedValue' => [
+                    'arrayOfPersonData' => [
+                        'john-doe' => ['firstName' => 'John', 'lastName' => 'Doe', 'fullName' => 'John Doe'],
+                        'jane-doe' => ['firstName' => 'Jane', 'lastName' => 'Doe', 'fullName' => 'Jane Doe'],
+                    ]
+                ],
+                'propertyName' => 'arrayOfPersonData',
+                'expectedDeserializedValue' => [
+                    'john-doe' => new PersonData('John', 'Doe'),
+                    'jane-doe' => new PersonData('Jane', 'Doe'),
+                ]
             ]
         ];
     }