Add more examples

Author: Kirill Nesmeyanov

example/01.normalization/01.object-normalization.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+use TypeLang\Mapper\Mapper;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+class ExampleDTO
+{
+    public function __construct(
+        public readonly string $value,
+    ) {}
+}
+
+$mapper = new Mapper();
+
+$result = $mapper->normalize(new ExampleDTO(value: 'testing'));
+
+var_dump($result);
+
+//
+// array:1 [
+//   "value" => "testing"
+// ]
+//

example/01.normalization/02.date-normalization.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+use TypeLang\Mapper\Mapper;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+$mapper = new Mapper();
+
+// Normalize date object to default RFC3339 string.
+$result = $mapper->normalize(new \DateTimeImmutable());
+
+var_dump($result);
+//
+// string(25) "2024-06-29T16:16:41+00:00"
+//

example/01.normalization/03.date-format-normalization.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+use TypeLang\Mapper\Mapper;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+$mapper = new Mapper();
+
+// Normalize date object to "d-m-Y" string.
+$result = $mapper->normalize(new \DateTimeImmutable(), 'datetime<"d-m-Y">');
+
+var_dump($result);
+//
+// string(10) "15-10-2024"
+//

example/02.object-normalization.php renamed to example/01.normalization/04.untyped-object-normalization.php

@@ -4,12 +4,7 @@
 
 use TypeLang\Mapper\Mapper;
 
-require __DIR__ . '/../vendor/autoload.php';
-
-// An example of converting an arbitrary object into primitive data.
-//
-// Please note that the type of the array (ExampleDTO::$children) is not
-// specified, which means it will be normalized "as is".
+require __DIR__ . '/../../vendor/autoload.php';
 
 class ChildDTO
 {
@@ -36,6 +31,7 @@ public function __construct(
 ));
 
 var_dump($result);
+
 //
 // array:1 [
 //   "children" => array:3 [

example/03.typed-object-normalization.php renamed to example/01.normalization/05.typed-object-normalization.php

@@ -7,7 +7,7 @@
 use TypeLang\Mapper\Mapping\MapProperty;
 use TypeLang\Mapper\Platform\StandardPlatform;
 
-require __DIR__ . '/../vendor/autoload.php';
+require __DIR__ . '/../../vendor/autoload.php';
 
 // The attribute driver is used to specify default types. To specify a specific
 // type, just add the #[MapProperty] attribute.
@@ -29,9 +29,7 @@ public function __construct(
     ) {}
 }
 
-$mapper = new Mapper(new StandardPlatform(
-    driver: new AttributeDriver(),
-));
+$mapper = new Mapper();
 
 $result = $mapper->normalize(new ExampleDTO(
     children: [
@@ -41,6 +39,8 @@ public function __construct(
     ]
 ));
 
+var_dump($result);
+
 //
 // InvalidValueException: Passed value must be of type ChildDTO{name: string},
 //                        but int (42) given at $.children[2]

example/01.normalization/06.inherited-types-normalization.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+use TypeLang\Mapper\Mapper;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+class ItemDTO
+{
+    public function __construct(
+        public readonly string $value,
+    ) {}
+}
+
+class ItemsResultDTO
+{
+    public function __construct(
+        public readonly array $items,
+    ) {}
+}
+
+$mapper = new Mapper();
+
+$value = new ItemsResultDTO([
+    'key1' => new ItemDTO(value: 'first'),
+    'key2' => new ItemDTO(value: 'second'),
+    new ItemDTO(value: 'third'),
+]);
+
+$result = $mapper->normalize($value);
+
+dd($result);
+//
+// array:1 [
+//   "items" => array:3 [
+//     "key1" => array:1 [
+//       "value" => "first"
+//     ]
+//     "key2" => array:1 [
+//       "value" => "second"
+//     ]
+//     0 => array:1 [
+//       "value" => "third"
+//     ]
+//   ]
+// ]
+//

example/01.normalization/07.collection-types-normalization.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+use TypeLang\Mapper\Mapper;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+class ItemDTO
+{
+    public function __construct(
+        public readonly string $value,
+    ) {}
+}
+
+class ItemsCollection implements \IteratorAggregate
+{
+    public function __construct(
+        private readonly array $items,
+    ) {}
+
+    public function getIterator(): Traversable
+    {
+        return new \ArrayIterator($this->items);
+    }
+}
+
+$mapper = new Mapper();
+
+$value = new ItemsCollection([
+    'key1' => new ItemDTO(value: 'first'),
+    'key2' => new ItemDTO(value: 'second'),
+    new ItemDTO(value: 'third'),
+]);
+
+// Transform collection of ItemDTO to list (array without keys)
+// of normalized ItemDTO (key-val array)
+$result = $mapper->normalize($value, 'list<ItemDTO>');
+
+var_dump($result);
+//
+// array:3 [
+//   0 => array:1 [
+//     "value" => "first"
+//   ]
+//   1 => array:1 [
+//     "value" => "second"
+//   ]
+//   2 => array:1 [
+//     "value" => "third"
+//   ]
+// ]
+//

example/01.normalization/08.object-output-normalization.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+use TypeLang\Mapper\Mapper;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+class ItemDTO
+{
+    public function __construct(
+        public readonly string $value,
+    ) {}
+}
+
+class ItemsResultDTO
+{
+    public function __construct(
+        public readonly array $items,
+    ) {}
+}
+
+$mapper = (new Mapper())
+    ->withObjectsAsArrays(false);
+
+$value = new ItemsResultDTO([
+    'key1' => new ItemDTO(value: 'first'),
+    'key2' => new ItemDTO(value: 'second'),
+    new ItemDTO(value: 'third'),
+]);
+
+$result = $mapper->normalize($value);
+
+var_dump($result);
+//
+// object{
+//   items: array:3 [
+//     "key1" => object{
+//       value: "first"
+//     }
+//     "key2" => object{
+//       value: "second"
+//     }
+//     0 => object{
+//       value: "third"
+//     }
+//   ]
+// }
+//

example/01.simple-normalization.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+use TypeLang\Mapper\Exception\Mapping\MappingExceptionInterface;
+use TypeLang\Mapper\Mapper;
+use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Parser\Node\Name;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+class ExampleDTO
+{
+    public function __construct(
+        #[MapProperty(type: 'list<ExampleDTO>')]
+        public readonly array $values = [],
+    ) {}
+}
+
+$mapper = new Mapper();
+
+try {
+    $result = $mapper->denormalize([
+        'values' => [
+            ['values' => []],
+            ['values' => 42],
+        ]
+    ], ExampleDTO::class);
+} catch (MappingExceptionInterface $e) {
+    // Before: "list<ExampleDTO>"
+    var_dump($e->getMessage());
+    // Passed value of field "values" must be of type list<ExampleDTO>,
+    // but 42 given at $.values[1].values
+
+    // Replace all internal type names with common "object" keyword.
+    $e = $e->explain(fn (Name $name): ?Name => \class_exists($name->toString())
+        ? new Name('object')
+        : null);
+
+    // After: "list<object>"
+    var_dump($e->getMessage());
+    // Passed value of field "values" must be of type list<object>,
+    // but 42 given at $.values[1].values
+}