Improve detection of the type from a PHP variable

Author: GromNaN

docs/en/reference/custom-mapping-types.rst

@@ -9,6 +9,9 @@ In order to create a new mapping type you need to subclass
 ``Doctrine\ODM\MongoDB\Types\Type`` and implement/override
 the methods.
 
+Date Example: Mapping DateTimeImmutable with Timezone
+-----------------------------------------------------
+
 The following example defines a custom type that stores ``DateTimeInterface``
 instances as an embedded document containing a BSON date and accompanying
 timezone string. Those same embedded documents are then be translated back into
@@ -32,6 +35,7 @@ a ``DateTimeImmutable`` when the data is read from the database.
         // This trait provides default closureToPHP used during data hydration
         use ClosureToPHP;
 
+        /** @param array{utc: UTCDateTime, tz: string} $value */
         public function convertToPHPValue($value): DateTimeImmutable
         {
             if (!isset($value['utc'], $value['tz'])) {
@@ -46,6 +50,7 @@ a ``DateTimeImmutable`` when the data is read from the database.
             return DateTimeImmutable::createFromMutable($dateTime);
         }
 
+        /** @return array{utc: UTCDateTime, tz: string} */
         public function convertToDatabaseValue($value): array
         {
             if (!$value instanceof DateTimeImmutable) {
@@ -115,5 +120,114 @@ specify a unique name for the mapping type and map that to the corresponding
 
         <field field-name="field" type="date_with_timezone" />
 
+Custom Type Example: Mapping a UUID Class
+-----------------------------------------
+
+You can create a custom mapping type for your own value objects or classes. For
+example, to map a UUID value object using the `ramsey/uuid library`_, you can
+implement a type that converts between your class and the BSON Binary UUID format.
+
+This approach works for any custom class by adapting the conversion logic to your needs.
+
+Example Implementation (using ``Ramsey\Uuid\Uuid``)::
+
+.. code-block:: php
+
+    <?php
+
+    namespace My\Project\Types;
+
+    use Doctrine\ODM\MongoDB\Types\ClosureToPHP;
+    use Doctrine\ODM\MongoDB\Types\Type;
+    use InvalidArgumentException;
+    use MongoDB\BSON\Binary;
+    use Ramsey\Uuid\Uuid;
+    use Ramsey\Uuid\UuidInterface;
+
+    final class UuidType extends Type
+    {
+        // This trait provides default closureToPHP used during data hydration
+        use ClosureToPHP;
+
+        public function convertToPHPValue(mixed $value): ?Uuid
+        {
+            if (null === $value) {
+                return null;
+            }
+
+            if ($value instanceof Uuid) {
+                return $value;
+            }
+
+            if ($value instanceof Binary) {
+                return Uuid::fromBytes($value->getData());
+            }
+
+            if (is_string($value) && Uuid::isValid($value)) {
+                return Uuid::fromString($value);
+            }
+
+            throw new InvalidArgumentException(
+                sprintf(
+                    'Could not convert database value "%s" from "%s" to %s',
+                    $value,
+                    get_debug_type($value),
+                    UuidInterface::class
+                )
+            );
+        }
+
+        public function convertToDatabaseValue(mixed $value): ?Binary
+        {
+            if (null === $value || [] === $value) {
+                return null;
+            }
+
+            if ($value instanceof Binary) {
+                return $value;
+            }
+
+            if (is_string($value) && Uuid::isValid($value)) {
+                $value = Uuid::fromString($value)->getBytes();
+            }
+
+            if ($value instanceof Uuid) {
+                return new Binary($value->getBytes(), Binary::TYPE_UUID);
+            }
+
+            throw new InvalidArgumentException(
+                sprintf(
+                    'Could not convert database value "%s" from "%s" to %s',
+                    $value,
+                    get_debug_type($value),
+                    Binary::class
+                )
+            );
+        }
+    }
+
+Register the type in your bootstrap code::
+
+.. code-block:: php
+
+    Type::addType(Ramsey\Uuid\Uuid::class, My\Project\Types\UuidType::class);
+
+Usage Example::
+
+.. code-block:: php
+
+    #[Field(type: Ramsey\Uuid\Uuid::class)]
+    public Ramsey\Uuid\Uuid $id;
+
+By using the |FQCN| of the value object class as the type name, the type is
+automatically used when encountering a property of that class. This means you
+can omit the ``type`` option when defining the field mapping::
+
+.. code-block:: php
+
+    #[Field]
+    public Ramsey\Uuid\Uuid $id;
+
+.. _`ramsey/uuid library`: https://github.com/ramsey/uuid
 .. |FQCN| raw:: html
   <abbr title="Fully-Qualified Class Name">FQCN</abbr>

lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php

@@ -2786,9 +2786,19 @@ private function isTypedProperty(string $name): bool
      */
     private function validateAndCompleteTypedFieldMapping(array $mapping): array
     {
+        if (isset($mapping['type'])) {
+            return $mapping;
+        }
+
         $type = $this->reflClass->getProperty($mapping['fieldName'])->getType();
 
-        if (! $type instanceof ReflectionNamedType || isset($mapping['type'])) {
+        if (! $type instanceof ReflectionNamedType) {
+            return $mapping;
+        }
+
+        if (! $type->isBuiltin() && Type::hasType($type->getName())) {
+            $mapping['type'] = $type->getName();
+
             return $mapping;
         }
 
@@ -2799,6 +2809,7 @@ private function validateAndCompleteTypedFieldMapping(array $mapping): array
                 throw MappingException::nonBackedEnumMapped($this->name, $mapping['fieldName'], $reflection->getName());
             }
 
+            // Use the backing type of the enum for the mapping type
             $type = $reflection->getBackingType();
             assert($type instanceof ReflectionNamedType);
             $mapping['enumType'] = $reflection->getName();

lib/Doctrine/ODM/MongoDB/Types/InvalidTypeException.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ODM\MongoDB\Types;
+
+use InvalidArgumentException;
+
+use function sprintf;
+
+final class InvalidTypeException extends InvalidArgumentException
+{
+    public static function invalidTypeName(string $name): self
+    {
+        return new self(sprintf('Invalid type specified: "%s"', $name));
+    }
+}

lib/Doctrine/ODM/MongoDB/Types/Type.php

@@ -4,18 +4,16 @@
 
 namespace Doctrine\ODM\MongoDB\Types;
 
+use DateTimeImmutable;
 use DateTimeInterface;
 use Doctrine\ODM\MongoDB\Mapping\MappingException;
 use Doctrine\ODM\MongoDB\Types;
-use InvalidArgumentException;
-use MongoDB\BSON\ObjectId;
 use Symfony\Component\Uid\Uuid;
 
 use function end;
 use function explode;
 use function gettype;
 use function is_object;
-use function sprintf;
 use function str_replace;
 
 /**
@@ -143,52 +141,52 @@ public static function registerType(string $name, string $class): void
     /**
      * Get a Type instance.
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidTypeException
      */
     public static function getType(string $type): Type
     {
         if (! isset(self::$typesMap[$type])) {
-            throw new InvalidArgumentException(sprintf('Invalid type specified "%s".', $type));
+            throw InvalidTypeException::invalidTypeName($type);
         }
 
-        if (! isset(self::$typeObjects[$type])) {
-            $className                = self::$typesMap[$type];
-            self::$typeObjects[$type] = new $className();
-        }
-
-        return self::$typeObjects[$type];
+        return self::$typeObjects[$type] ??= new (self::$typesMap[$type]);
     }
 
     /**
      * Get a Type instance based on the type of the passed php variable.
      *
      * @param mixed $variable
-     *
-     * @throws InvalidArgumentException
      */
     public static function getTypeFromPHPVariable($variable): ?Type
     {
         if (is_object($variable)) {
-            if ($variable instanceof DateTimeInterface) {
-                return self::getType(self::DATE);
+            if ($variable instanceof DateTimeImmutable) {
+                return self::getType(self::DATE_IMMUTABLE);
             }
 
-            if ($variable instanceof ObjectId) {
-                return self::getType(self::ID);
+            if ($variable instanceof DateTimeInterface) {
+                return self::getType(self::DATE);
             }
 
             if ($variable instanceof Uuid) {
                 return self::getType(self::UUID);
             }
-        } else {
-            $type = gettype($variable);
-            switch ($type) {
-                case 'integer':
-                    return self::getType('int');
+
+            // Try the variable class as type name
+            if (self::hasType($variable::class)) {
+                return self::getType($variable::class);
             }
+
+            return null;
         }
 
-        return null;
+        return match (gettype($variable)) {
+            'integer' => self::getType(self::INT),
+            'boolean' => self::getType(self::BOOL),
+            'double' => self::getType(self::FLOAT),
+            'string' => self::getType(self::STRING),
+            default => null,
+        };
     }
 
     /**