Add basic discriminator map support

Kirill Nesmeyanov · Kirill Nesmeyanov · commit e2a422f8bed9 · 2024-11-19T13:21:23.000+03:00
diff --git a/src/Mapping/DiscriminatorMap.php b/src/Mapping/DiscriminatorMap.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Mapping;
+
+/**
+ * ```
+ * #[DiscriminatorMap(field: 'type', map: [
+ *     'admin' => Admin::class,
+ *     'moderator' => Moderator::class,
+ *     'user' => User::class,
+ *     'any' => 'array<array-key, string>'
+ * ])]
+ * abstract class Account {}
+ *
+ * final class Admin extends Account {}
+ * final class Moderator extends Account {}
+ * final class User extends Account {}
+ * ```
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class DiscriminatorMap
+{
+    public function __construct(
+        /**
+         * @var non-empty-string
+         */
+        public readonly string $field,
+        /**
+         * @var array<non-empty-string, non-empty-string>
+         */
+        public readonly array $map,
+    ) {}
+}
diff --git a/src/Mapping/Driver/AttributeDriver.php b/src/Mapping/Driver/AttributeDriver.php
@@ -9,9 +9,11 @@
 use TypeLang\Mapper\Exception\Definition\PropertyTypeNotFoundException;
 use TypeLang\Mapper\Exception\Definition\TypeNotFoundException;
 use TypeLang\Mapper\Exception\Environment\ComposerPackageRequiredException;
+use TypeLang\Mapper\Mapping\DiscriminatorMap;
 use TypeLang\Mapper\Mapping\MapName;
 use TypeLang\Mapper\Mapping\MapType;
 use TypeLang\Mapper\Mapping\Metadata\ClassMetadata;
+use TypeLang\Mapper\Mapping\Metadata\DiscriminatorMapMetadata;
 use TypeLang\Mapper\Mapping\Metadata\ExpressionMetadata;
 use TypeLang\Mapper\Mapping\Metadata\TypeMetadata;
 use TypeLang\Mapper\Mapping\NormalizeAsArray;
@@ -124,6 +126,19 @@ protected function load(
                 ));
             }
         }
+
+        // -----------------------------------------------------------------
+        //  Apply discriminator logic
+        // -----------------------------------------------------------------
+
+        $attribute = $this->findClassAttribute($reflection, DiscriminatorMap::class);
+
+        if ($attribute !== null) {
+            $class->setDiscriminator(new DiscriminatorMapMetadata(
+                field: $attribute->field,
+                map: $attribute->map,
+            ));
+        }
     }
 
     /**
diff --git a/src/Mapping/Metadata/ClassMetadata.php b/src/Mapping/Metadata/ClassMetadata.php
@@ -32,20 +32,28 @@ final class ClassMetadata extends Metadata
      */
     private ?bool $normalizeAsArray = null;
 
+    /**
+     * Contains a {@see DiscriminatorMapMetadata} instance in case of class-like
+     * contains a discriminator map.
+     */
+    private ?DiscriminatorMapMetadata $discriminator;
+
     /**
      * @param class-string<T> $name
      * @param iterable<array-key, PropertyMetadata> $properties
      */
     public function __construct(
         private readonly string $name,
         iterable $properties = [],
+        ?DiscriminatorMapMetadata $discriminator = null,
         ?int $createdAt = null,
     ) {
         parent::__construct($createdAt);
 
         foreach ($properties as $property) {
             $this->addProperty($property);
         }
+        $this->discriminator = $discriminator;
     }
 
     /**
@@ -183,4 +191,38 @@ public function getProperties(): array
     {
         return \array_values($this->properties);
     }
+
+    /**
+     * Returns {@see DiscriminatorMapMetadata} information about a class
+     * discriminator map, or returns {@see null} if no such metadata has been
+     * registered in the {@see ClassMetadata} instance.
+     *
+     * @api
+     */
+    public function findDiscriminator(): ?DiscriminatorMapMetadata
+    {
+        return $this->discriminator;
+    }
+
+    /**
+     * Returns {@see true} if the {@see DiscriminatorMapMetadata} information
+     * was registered in the {@see ClassMetadata}  and {@see false} otherwise.
+     *
+     * @api
+     */
+    public function hasDiscriminator(): bool
+    {
+        return $this->discriminator !== null;
+    }
+
+    /**
+     * Updates {@see DiscriminatorMapMetadata} information about a class
+     * discriminator map.
+     *
+     * @api
+     */
+    public function setDiscriminator(?DiscriminatorMapMetadata $discriminator): void
+    {
+        $this->discriminator = $discriminator;
+    }
 }
diff --git a/src/Mapping/Metadata/DiscriminatorMapMetadata.php b/src/Mapping/Metadata/DiscriminatorMapMetadata.php
@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\Mapper\Mapping\Metadata;
+
+/**
+ * Represents an abstraction over general information about a class.
+ */
+final class DiscriminatorMapMetadata extends Metadata
+{
+    public function __construct(
+        /**
+         * @var non-empty-string
+         */
+        private readonly string $field,
+        /**
+         * @var array<non-empty-string, non-empty-string>
+         */
+        private array $map = [],
+        ?int $createdAt = null,
+    ) {
+        parent::__construct($createdAt);
+    }
+
+    /**
+     * Returns class for the passed value of the defined {@see $field}.
+     *
+     * @return non-empty-string|null
+     */
+    public function findType(string $fieldValue): ?string
+    {
+        return $this->map[$fieldValue] ?? null;
+    }
+
+    /**
+     * Returns {@see true} in case of the passed value of the
+     * defined {@see $field} is mapped on class.
+     */
+    public function hasType(string $fieldValue): bool
+    {
+        return $this->findType($fieldValue) !== null;
+    }
+
+    /**
+     * Returns class mapping.
+     *
+     * @return array<non-empty-string, non-empty-string>
+     */
+    public function getMapping(): array
+    {
+        return $this->map;
+    }
+
+    /**
+     * Returns discriminator field name.
+     *
+     * @api
+     *
+     * @return non-empty-string
+     */
+    public function getField(): string
+    {
+        return $this->field;
+    }
+}
diff --git a/src/Type/Builder/ClassTypeBuilder.php b/src/Type/Builder/ClassTypeBuilder.php
@@ -4,6 +4,7 @@
 
 namespace TypeLang\Mapper\Type\Builder;
 
+use TypeLang\Mapper\Exception\Definition\InternalTypeException;
 use TypeLang\Mapper\Mapping\Driver\DriverInterface;
 use TypeLang\Mapper\Mapping\Driver\ReflectionDriver;
 use TypeLang\Mapper\Runtime\Parser\TypeParserInterface;
@@ -49,7 +50,11 @@ public function isSupported(TypeStatement $statement): bool
 
         $reflection = new \ReflectionClass($name);
 
-        return $reflection->isInstantiable();
+        return $reflection->isInstantiable()
+            // Allow abstract classes for discriminators
+            || $reflection->isAbstract()
+            // Allow interfaces for discriminators
+            || $reflection->isInterface();
     }
 
     public function build(
@@ -63,12 +68,30 @@ public function build(
         /** @var class-string<T> $class */
         $class = $statement->name->toString();
 
+        $reflection = new \ReflectionClass($class);
+
         $metadata = $this->driver->getClassMetadata(
-            class: new \ReflectionClass($class),
+            class: $reflection,
             types: $types,
             parser: $parser,
         );
 
+        $discriminator = $metadata->findDiscriminator();
+
+        if ($discriminator === null && !$reflection->isInstantiable()) {
+            throw InternalTypeException::becauseInternalTypeErrorOccurs(
+                type: $statement,
+                message: \vsprintf('%s "%s" expects a discriminator map to be able to be created', [
+                    match (true) {
+                        $reflection->isAbstract() => 'Non-creatable abstract class',
+                        $reflection->isInterface() => 'Non-creatable interface',
+                        default => 'Unknown non-instantiable type',
+                    },
+                    $reflection->getName(),
+                ]),
+            );
+        }
+
         return new ClassType(
             metadata: $metadata,
             accessor: $this->accessor,
diff --git a/src/Type/ClassType/ClassTypeDenormalizer.php b/src/Type/ClassType/ClassTypeDenormalizer.php
@@ -4,13 +4,16 @@
 
 namespace TypeLang\Mapper\Type\ClassType;
 
+use TypeLang\Mapper\Exception\Definition\TypeNotFoundException;
 use TypeLang\Mapper\Exception\Mapping\FieldExceptionInterface;
 use TypeLang\Mapper\Exception\Mapping\InvalidFieldTypeValueException;
 use TypeLang\Mapper\Exception\Mapping\InvalidValueMappingException;
 use TypeLang\Mapper\Exception\Mapping\MappingExceptionInterface;
 use TypeLang\Mapper\Exception\Mapping\MissingFieldTypeException;
 use TypeLang\Mapper\Exception\Mapping\MissingFieldValueException;
+use TypeLang\Mapper\Exception\Mapping\RuntimeExceptionInterface;
 use TypeLang\Mapper\Mapping\Metadata\ClassMetadata;
+use TypeLang\Mapper\Mapping\Metadata\DiscriminatorMapMetadata;
 use TypeLang\Mapper\Runtime\Context;
 use TypeLang\Mapper\Runtime\Path\Entry\ObjectEntry;
 use TypeLang\Mapper\Runtime\Path\Entry\ObjectPropertyEntry;
@@ -38,9 +41,14 @@ public function match(mixed $value, Context $context): bool
     }
 
     /**
-     * @return T
+     * @return T|mixed
+     * @throws InvalidValueMappingException
+     * @throws MissingFieldValueException
+     * @throws RuntimeExceptionInterface
+     * @throws TypeNotFoundException
+     * @throws \Throwable
      */
-    public function cast(mixed $value, Context $context): object
+    public function cast(mixed $value, Context $context): mixed
     {
         if (\is_object($value)) {
             $value = (array) $value;
@@ -54,6 +62,12 @@ public function cast(mixed $value, Context $context): object
             );
         }
 
+        $discriminator = $this->metadata->findDiscriminator();
+
+        if ($discriminator !== null) {
+            return $this->castOverDiscriminator($discriminator, $value, $context);
+        }
+
         $entrance = $context->enter($value, new ObjectEntry($this->metadata->getName()));
 
         $instance = $this->instantiator->instantiate($this->metadata);
@@ -63,6 +77,42 @@ public function cast(mixed $value, Context $context): object
         return $instance;
     }
 
+    /**
+     * @param array<array-key, mixed> $value
+     * @throws MissingFieldValueException
+     * @throws \Throwable
+     * @throws TypeNotFoundException
+     * @throws RuntimeExceptionInterface
+     */
+    private function castOverDiscriminator(DiscriminatorMapMetadata $map, array $value, Context $context): mixed
+    {
+        $discriminatorValue = $value[$map->getField()] ?? null;
+
+        // Invalid discriminator field type
+        if (!\is_string($discriminatorValue)) {
+            throw MissingFieldValueException::createFromContext(
+                expected: $this->metadata->getTypeStatement($context),
+                field: $map->getField(),
+                context: $context,
+            );
+        }
+
+        $discriminatorDefinition = $map->findType($discriminatorValue);
+
+        // Invalid discriminator type
+        if ($discriminatorDefinition === null) {
+            throw MissingFieldValueException::createFromContext(
+                expected: $this->metadata->getTypeStatement($context),
+                field: $map->getField(),
+                context: $context,
+            );
+        }
+
+        $discriminatorType = $context->getTypeByDefinition($discriminatorDefinition);
+
+        return $discriminatorType->cast($value, $context);
+    }
+
     /**
      * @param array<array-key, mixed> $value
      *
