Split MapProperty attribute to MapType + MapName and add SkipWhen attribute + metadata support

Kirill Nesmeyanov · Kirill Nesmeyanov · commit 8594b21a4152 · 2024-10-16T17:03:02.000+03:00
diff --git a/README.md b/README.md
@@ -102,12 +102,12 @@ Normalization: Transformation from object to raw payload (array).
 ## Quick Start
 
 ```php
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 
 class ExampleObject
 {
     public function __construct(
-        #[MapProperty('list<non-empty-string>')]
+        #[MapType('list<non-empty-string>')]
         public readonly array $names,
     ) {}
 }
diff --git a/example/01.normalization/05.typed-object-normalization.php b/example/01.normalization/05.typed-object-normalization.php
@@ -3,7 +3,7 @@
 declare(strict_types=1);
 
 use TypeLang\Mapper\Mapper;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
@@ -22,7 +22,7 @@ public function __construct(
 class ExampleDTO
 {
     public function __construct(
-        #[MapProperty('list<ChildDTO>')]
+        #[MapType('list<ChildDTO>')]
         public readonly array $children = [],
     ) {}
 }
diff --git a/example/02.errors/01.errors-purification.php b/example/02.errors/01.errors-purification.php
@@ -4,15 +4,15 @@
 
 use TypeLang\Mapper\Exception\Mapping\MappingExceptionInterface;
 use TypeLang\Mapper\Mapper;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 use TypeLang\Parser\Node\Name;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
 class ExampleDTO
 {
     public function __construct(
-        #[MapProperty(type: 'list<ExampleDTO>')]
+        #[MapType(type: 'list<ExampleDTO>')]
         public readonly array $values = [],
     ) {}
 }
diff --git a/example/02.errors/02.custom-type-printer.php b/example/02.errors/02.custom-type-printer.php
@@ -3,15 +3,15 @@
 declare(strict_types=1);
 
 use TypeLang\Mapper\Mapper;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 use TypeLang\Mapper\Exception\Mapping\RuntimeException;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
 class ExampleDTO
 {
     public function __construct(
-        #[MapProperty(type: 'list<ExampleDTO>')]
+        #[MapType(type: 'list<ExampleDTO>')]
         public readonly array $values = [],
     ) {}
 }
diff --git a/example/02.errors/03.extended-type-printer.php b/example/02.errors/03.extended-type-printer.php
@@ -3,7 +3,7 @@
 declare(strict_types=1);
 
 use TypeLang\Mapper\Mapper;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 use TypeLang\Mapper\Exception\Mapping\RuntimeException;
 use TypeLang\Parser\Node\Stmt\NamedTypeNode;
 use TypeLang\Printer\PrettyPrinter;
@@ -13,7 +13,7 @@
 class ExampleDTO
 {
     public function __construct(
-        #[MapProperty(type: 'list<ExampleDTO>')]
+        #[MapType(type: 'list<ExampleDTO>')]
         public readonly array $values = [],
     ) {}
 }
diff --git a/example/02.errors/04.custom-path-printer.php b/example/02.errors/04.custom-path-printer.php
@@ -3,7 +3,7 @@
 declare(strict_types=1);
 
 use TypeLang\Mapper\Mapper;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 use TypeLang\Mapper\Exception\Mapping\RuntimeException;
 use TypeLang\Mapper\Runtime\Value\SimpleValuePrinter;
 
@@ -12,7 +12,7 @@
 class ExampleDTO
 {
     public function __construct(
-        #[MapProperty(type: 'list<ExampleDTO>')]
+        #[MapType(type: 'list<ExampleDTO>')]
         public readonly array $values = [],
     ) {}
 }
diff --git a/example/02.errors/05.custom-value-printer.php b/example/02.errors/05.custom-value-printer.php
@@ -3,7 +3,7 @@
 declare(strict_types=1);
 
 use TypeLang\Mapper\Mapper;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 use TypeLang\Mapper\Exception\Mapping\RuntimeException;
 use TypeLang\Mapper\Runtime\Path\PathInterface;
 use TypeLang\Mapper\Runtime\Path\PathPrinterInterface;
@@ -13,7 +13,7 @@
 class ExampleDTO
 {
     public function __construct(
-        #[MapProperty(type: 'list<ExampleDTO>')]
+        #[MapType(type: 'list<ExampleDTO>')]
         public readonly array $values = [],
     ) {}
 }
diff --git a/example/04.mapping/02.attribute-mapping.php b/example/04.mapping/02.attribute-mapping.php
@@ -3,15 +3,15 @@
 declare(strict_types=1);
 
 use TypeLang\Mapper\Mapper;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
 class ExampleDTO
 {
     public function __construct(
         public readonly int $value1 = 0,
-        #[MapProperty('int<min, 0>')]
+        #[MapType('int<min, 0>')]
         public readonly int $value2 = 0,
     ) {}
 }
diff --git a/example/04.mapping/03.driver-inheritance-mapping.php b/example/04.mapping/03.driver-inheritance-mapping.php
@@ -3,15 +3,15 @@
 declare(strict_types=1);
 
 use TypeLang\Mapper\Mapper;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapType;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
 class ExampleDTO
 {
     public function __construct(
         public readonly int $value1 = 0,
-        #[MapProperty('int<min, 0>')]
+        #[MapType('int<min, 0>')]
         public readonly int $value2 = 0,
     ) {}
 }
diff --git a/src/Mapping/Driver/AttributeDriver.php b/src/Mapping/Driver/AttributeDriver.php
@@ -6,9 +6,11 @@
 
 use TypeLang\Mapper\Exception\Definition\PropertyTypeNotFoundException;
 use TypeLang\Mapper\Exception\Definition\TypeNotFoundException;
-use TypeLang\Mapper\Mapping\MapProperty;
+use TypeLang\Mapper\Mapping\MapName;
+use TypeLang\Mapper\Mapping\MapType;
 use TypeLang\Mapper\Mapping\Metadata\ClassMetadata;
 use TypeLang\Mapper\Mapping\Metadata\TypeMetadata;
+use TypeLang\Mapper\Mapping\SkipWhen;
 use TypeLang\Mapper\Type\Repository\RepositoryInterface;
 
 final class AttributeDriver extends LoadableDriver
@@ -17,43 +19,68 @@ final class AttributeDriver extends LoadableDriver
     protected function load(\ReflectionClass $reflection, ClassMetadata $class, RepositoryInterface $types): void
     {
         foreach ($reflection->getProperties() as $property) {
-            $attribute = $this->findPropertyAttribute(
-                property: $property,
-                class: MapProperty::class,
-            );
+            $metadata = $class->getPropertyOrCreate($property->getName());
+
+            // -----------------------------------------------------------------
+            //  Apply property type
+            // -----------------------------------------------------------------
+
+            $attribute = $this->findPropertyAttribute($property, MapType::class);
+
+            if ($attribute !== null) {
+                $type = $this->createType($attribute->type, $property, $types);
 
-            if ($attribute === null) {
-                continue;
+                $metadata->setTypeInfo($type);
             }
 
-            $metadata = $class->getPropertyOrCreate($property->getName());
+            // -----------------------------------------------------------------
+            //  Apply property name
+            // -----------------------------------------------------------------
+
+            $attribute = $this->findPropertyAttribute($property, MapName::class);
 
-            if ($attribute->name !== null) {
+            if ($attribute !== null) {
                 $metadata->setExportName($attribute->name);
             }
 
-            if ($attribute->type !== null) {
-                $statement = $types->parse($attribute->type);
-
-                try {
-                    $type = $types->getByStatement($statement, $reflection);
-                } catch (TypeNotFoundException $e) {
-                    throw PropertyTypeNotFoundException::becauseTypeOfPropertyNotDefined(
-                        class: $class->getName(),
-                        property: $property->getName(),
-                        type: $e->getType(),
-                        previous: $e,
-                    );
-                }
-
-                $metadata->setTypeInfo(new TypeMetadata(
-                    type: $type,
-                    statement: $statement,
-                ));
+            // -----------------------------------------------------------------
+            //  Apply skip condition
+            // -----------------------------------------------------------------
+
+            $attribute = $this->findPropertyAttribute($property, SkipWhen::class);
+
+            if ($attribute !== null) {
+                $type = $this->createType($attribute->type, $property, $types);
+
+                $metadata->setSkipCondition($type);
             }
         }
     }
 
+    /**
+     * @param non-empty-string $type
+     * @throws PropertyTypeNotFoundException
+     */
+    private function createType(string $type, \ReflectionProperty $property, RepositoryInterface $types): TypeMetadata
+    {
+        $statement = $types->parse($type);
+
+        $class = $property->getDeclaringClass();
+
+        try {
+            $instance = $types->getByStatement($statement, $class);
+        } catch (TypeNotFoundException $e) {
+            throw PropertyTypeNotFoundException::becauseTypeOfPropertyNotDefined(
+                class: $class->getName(),
+                property: $property->getName(),
+                type: $e->getType(),
+                previous: $e,
+            );
+        }
+
+        return new TypeMetadata($instance, $statement);
+    }
+
     /**
      * @template TAttribute of object
      *
diff --git a/src/Mapping/MapName.php b/src/Mapping/MapName.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Mapping;
+
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+class MapName
+{
+    public function __construct(
+        /**
+         * @var non-empty-string
+         */
+        public readonly string $name,
+    ) {}
+}
diff --git a/src/Mapping/MapProperty.php b/src/Mapping/MapProperty.php
diff --git a/src/Mapping/MapType.php b/src/Mapping/MapType.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Mapping;
+
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+class MapType
+{
+    public function __construct(
+        /**
+         * @var non-empty-string
+         */
+        public readonly string $type,
+    ) {}
+}
diff --git a/src/Mapping/Metadata/PropertyMetadata.php b/src/Mapping/Metadata/PropertyMetadata.php
@@ -20,6 +20,8 @@ final class PropertyMetadata extends Metadata
 
     private bool $hasDefaultValue = false;
 
+    private ?TypeMetadata $skipWhen = null;
+
     /**
      * @param non-empty-string $export
      */
@@ -152,6 +154,43 @@ public function findTypeInfo(): ?TypeMetadata
         return $this->type;
     }
 
+    /**
+     * @api
+     */
+    public function setSkipCondition(TypeMetadata $type): void
+    {
+        $this->skipWhen = $type;
+    }
+
+    /**
+     * @api
+     */
+    public function removeSkipCondition(): void
+    {
+        $this->skipWhen = null;
+    }
+
+    /**
+     * @api
+     */
+    public function hasSkipCondition(): bool
+    {
+        return $this->skipWhen !== null;
+    }
+
+    /**
+     * Note: The prefix "find" is used to indicate that the {@see TypeMetadata}
+     *       definition may be optional and method may return {@see null}.
+     *       The prefix "get" is used when the value is forced to be obtained
+     *       and should throw an exception if the type definition is missing.
+     *
+     * @api
+     */
+    public function findSkipCondition(): ?TypeMetadata
+    {
+        return $this->skipWhen;
+    }
+
     /**
      * @api
      */
diff --git a/src/Mapping/SkipWhen.php b/src/Mapping/SkipWhen.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Mapping;
+
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+class SkipWhen
+{
+    public function __construct(
+        /**
+         * @var non-empty-string
+         */
+        public readonly string $type,
+    ) {}
+}
diff --git a/tests/Bench/Stub/ExampleRequestDTO.php b/tests/Bench/Stub/ExampleRequestDTO.php

Original file line number	Diff line number	Diff line change
`@@ -102,12 +102,12 @@ Normalization: Transformation from object to raw payload (array).`
`102`	`102`	`## Quick Start`
`103`	`103`
`104`	`104`	```php
`105`		`-use TypeLang\Mapper\Mapping\MapProperty;`
	`105`	`+use TypeLang\Mapper\Mapping\MapType;`
`106`	`106`
`107`	`107`	`class ExampleObject`
`108`	`108`	`{`
`109`	`109`	`public function __construct(`
`110`		`- #[MapProperty('list<non-empty-string>')]`
	`110`	`+ #[MapType('list<non-empty-string>')]`
`111`	`111`	`public readonly array $names,`
`112`	`112`	`) {}`
`113`	`113`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`declare(strict_types=1);`
`4`	`4`
`5`	`5`	`use TypeLang\Mapper\Mapper;`
`6`		`-use TypeLang\Mapper\Mapping\MapProperty;`
	`6`	`+use TypeLang\Mapper\Mapping\MapType;`
`7`	`7`
`8`	`8`	`require __DIR__ . '/../../vendor/autoload.php';`
`9`	`9`
`@@ -22,7 +22,7 @@ public function __construct(`
`22`	`22`	`class ExampleDTO`
`23`	`23`	`{`
`24`	`24`	`public function __construct(`
`25`		`- #[MapProperty('list<ChildDTO>')]`
	`25`	`+ #[MapType('list<ChildDTO>')]`
`26`	`26`	`public readonly array $children = [],`
`27`	`27`	`) {}`
`28`	`28`	`}`