Add documentation for custom type covering value object

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
@@ -115,5 +118,108 @@ specify a unique name for the mapping type and map that to the corresponding
 
         <field field-name="field" type="date_with_timezone" />
 
-.. |FQCN| raw:: html
-  <abbr title="Fully-Qualified Class Name">FQCN</abbr>
+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 MongoDB binary format.
+
+This approach works for any custom class—just adapt the conversion logic to your needs.
+
+Example Implementation (using Ramsey\Uuid\UuidInterface)::
+
+
+.. 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
+    {
+        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
+                )
+            );
+        }
+    }
+
+Usage Example::
+
+.. code-block:: php
+
+    #[Field(type: Uuid::class)]
+    public Uuid $id;
+
+Register the type in your bootstrap code::
+
+.. code-block:: php
+
+    Type::addType(Ramsey\Uuid\Uuid::class, My\Project\Types\UuidType::class);
+
+.. note::
+   The type name should match the support class name (e.g., ``uuid`` for ``UuidType``) to enable automatic association with the field type.
+
+This pattern can be adapted for any custom class—just implement the conversion logic for your value object.
+
+.. |FQCN| raw:: html <abbr title="Fully-Qualified Class Name">FQCN</abbr>
+.. _`ramsey/uuid library`: https://github.com/ramsey/uuid