From 2c20d58c4fddbccd7d2d06efe0ee3623ec6a9145 Mon Sep 17 00:00:00 2001
From: Hugo Rafael Azevedo <h.azevedo@exporo.com>
Date: Sun, 27 Mar 2022 18:11:25 +0100
Subject: [PATCH] docs: improve code snippets in main readme file

---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 56 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5a88a1b..370a689 100755
--- a/README.md
+++ b/README.md
@@ -12,12 +12,66 @@
 
 ## Code Usage
 
+This package is mean to provide you an easy way to do this (_and much more_):
+
+```php
+$user = new User([
+    'id' => 123,
+    'active' => true,
+    'name' => ' John Doe ',
+]);
+
+echo $user->getId(); // (int) 123
+echo $user->isActive(); // (bool) true
+echo $user->getName(); // Prints ' John Doe '
+echo $user->getName()->trim()->toUpper()->replace(' ', '-'); // Prints 'JOHN-DOE'
+echo $user->getName(); // Prints ' John Doe ' again, as Attribute is immutable.
+```
+
+... just by building your object like this:
+
+```php
+class User extends AbstractValueObject
+{
+    use HasPositiveIntegerIDTrait,
+        HasActiveTrait,
+        HasNameTrait;
+}
+```
+
+Also, out-of-box, it will allow you to do the following:
+
+```php
+$user = new User([
+    'id' => 123,
+    'active' => true,
+    'name' => ' John Doe ',
+]);
+
+echo json_encode($user); // {"id":123,"active":true,"name":"John Doe"}
+
+$serialized = serialize($user);
+$otherUser = unserialize($serialized);
+
+printf($otherUser->toArray());
+/*
+[
+    'id' => 123,
+    'active' => true,
+    'name' => 'John Doe',
+]
+*/
+```
+
+... and much more. This will leave your objects clean from repetitive state management code, which frees you to
+implement your business logic in them.
+
 In order to learn more about the code, please go [here](https://github.com/HRADigital/php-datatypes/blob/master/src/ValueObjects).
 
 ## About
 
-**PHP Datatypes** is meant to provide an easy way to create your Value Objects/Entities/Aggregates, in a fast and platform agnostic way,
-that promotes:
+**PHP Datatypes** is meant to provide an easy way to create your Value Objects/Entities/Aggregates, in a fast and
+platform agnostic way, that promotes:
 
 - Code reusability
 - Data normalization