Added documentation

Author: Fa-BRAIK

README.md

@@ -67,3 +67,5 @@ and if you are using Laravel, I highly recommend using the original package. ins
 
 - PHP 8.4 or higher
 - That's it!
+
+### Installation

src/Concerns/BaseData.php

@@ -112,14 +112,4 @@ 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();
-    }
 }

src/Data.php

@@ -4,8 +4,24 @@
 
 use Nuxtifyts\PhpDto\Contracts\BaseData as BaseDataContract;
 use Nuxtifyts\PhpDto\Concerns\BaseData;
+use Nuxtifyts\PhpDto\Exceptions\SerializeException;
 
 abstract readonly class Data implements BaseDataContract
 {
     use BaseData;
+
+    /**
+     * @return array<string, mixed>
+     *
+     * @throws SerializeException
+     */
+    final public function toArray(): array
+    {
+        return $this->jsonSerialize();
+    }
+
+    final public function toJson(): false|string
+    {
+        return json_encode($this);
+    }
 }

src/Docs/Introduction.md

@@ -0,0 +1,32 @@
+Introduction
+=
+
+This package enabled the creation of data objects which can be used in various ways.
+Using modern PHP syntax, it allows you to hydrate data from arrays, objects, and other data sources.
+As well as carrying out the data, type validation and serialize the data for any purpose.
+
+To create a `data` class, you will need to declare a `readonly` class that extends `Data` class.
+Then you can define the properties of the class and their types.
+
+```php
+use Nuxtifyts\PhpDto\Data;
+
+final readonly class UserData extends Data
+{
+    public string $fullName;
+
+    public function __construct(
+        public string $firstName,
+        public stirng $lastName
+    ) {
+        $this->fullName = "$this->firstName $this->lastName";
+    }
+}
+```
+
+By extending from `Data` you enable the ability to serialize/deserialize a data object.
+
+- Hydrating a data from a `mixed` value using normalizers
+- Serializing a data from a data object to an array or JSON.
+
+Checkout the [Quickstart](#) guide to get started with the package.

src/Docs/Normalizers.md

@@ -0,0 +1,100 @@
+Normalizers
+=
+
+When trying to hydrate a data object using the `from` function, the package will use normalizers to convert the passed
+data into (preferable) an `array`/`ArrayAccess`.
+
+By default, there are 4 normalizers:
+
+- **JsonStringNormalizer** will cast json string.
+- **StrClassNormalizer** will cast stdObject.
+- **ArrayAccessNormalizer** will cast ArrayAccess.
+- **ArrayNormalizer** will cast array.
+
+Custom normalizers:
+=
+
+Custom normalizers can be added if needed: To do this, you will need to extend the `Normalizer` class
+and implement the `normalize` method.
+
+For example: we have a custom class called: `Goal`: 
+
+```php
+class Goal
+{
+    public function __construct(
+        public string $summary,
+        public string $description,
+        public DateTimeImmutable $dueDate
+    ) {
+    }
+}
+```
+
+And we have our `Todo` data class: 
+
+```php
+use Nuxtifyts\PhpDto\Data;
+
+final readonly class Todo extends Data
+{
+    public function __construct(
+        public string $title,
+        public string $content,
+        public Status $status,
+        public ?DateTimeImmutable $dueDate
+    ) {
+    }
+}
+```
+
+And we want to hydrate instances of this class to using a normalizer. first, we need to create
+a normalizer class, we'll call it `GoalTodoNormalizer`:
+
+```php
+use Nuxtifyts\PhpDto\Normalizers\Normalizer;
+
+final readonly class GoalTodoNormalizer extends Normalizer
+{
+    public function normalize() : array|false{
+        if (!$this->value instanceof Goal) {
+            return false;
+        }
+        
+        return [
+            'title' => $this->value->summary,
+            'content' => $this->value->description,
+            'status' => 'ready',
+            'dueDate' => $this->value->dueDate->format(DateTimeInterface::ATOM)
+        ];   
+    }
+}
+```
+
+Next step is to add this new normalizer to the todo class:
+
+```php
+use Nuxtifyts\PhpDto\Data;
+
+final readonly class Todo extends Data
+{
+    // ...
+    
+    protected static function normalizers() : array{
+        return GoalTodoNormalizer::class;
+    }
+}
+```
+
+This will add the `GoalTodoNormalizer` on top of the default normalizers. Now it'll be possible to hydrate
+a `Todo` instance from a `Goal` instance.
+
+```php
+$goal = new Goal(
+    title: 'Learn PHP DTO',
+    description: 'Learn how to use PHP DTO',
+    dueDate: new DateTimeImmutable()
+);
+
+$todo = Todo::from($goal);
+```

src/Docs/Quickstart.md

@@ -0,0 +1,81 @@
+Quickstart
+=
+
+In this quickstart guide, you will learn the most basic usage of this package.
+
+First, you should [install](#) the package using composer:
+
+We will create a Todo application, where we need to manage a list of TODOs. so we can start
+with creating a `Todo` data class.
+
+```php
+use Nuxtifyts\PhpDto\Data;
+
+final readonly class Todo extends Data
+{
+    public function __construct(
+        public string $title,
+        public string $content,
+        public Status $status,
+        public ?DateTimeImmutable $dueDate
+    ) {}
+}
+```
+
+Extending from `Data` class is all you'll need to start using data transfer objects. 
+You can define the properties of the class and their types.
+
+In the above example, the `Status` a native `BackedEnum` class:
+
+```php
+enum Status: string
+{
+    case BACKLOG = 'backlog';
+    case READY = 'ready';
+    case IN_PROGRESS = 'in_progress';
+    case DONE = 'done';
+}
+```
+
+We can now create a new instance of the `Todo`:
+
+```php
+$todo = new Todo(
+    title: 'Learn PHP DTO',
+    content: 'Learn how to use PHP DTO',
+    status: Status::READY,
+    dueDate: new DateTimeImmutable()
+)
+```
+
+The package allows you to hydrate these data objects from other types, for example an array:
+
+```php
+$todo = Todo::from([
+    'title' => 'Learn PHP DTO',
+    'content' => 'Learn how to use PHP DTO',
+    'status' => 'ready',
+    'dueDate' => '2025-01-01T00:00:00+00:00'
+]);
+```
+
+You can also serialize the data object to an array, or a json string:
+
+```php
+// Serialize to an array
+$todo->toArray();
+
+// Serialize to a json string
+json_encode($todo); // or
+$todo->toJson();
+```
+
+Conclusion
+-
+
+This is the most basic usage of this package, more details on how to use the package 
+can be found here:
+
+- [Supported Types](#)
+- [Normalizers](#)
+- [Property Attributes (TBD)](#)