Add TypedFieldMapper for automatic mapping of typed PHP fields to DBA…

…L types (#10313)

Previously, only a predefined set of automatic mappings was allowed, such as int, float, boolean, DateTime etc.
With this extension, it is possible to supply custom TypedFieldMapper implementation which takes as parameter the ReflectionProperty of a given field and decides the appropriate mapping.
A new configuration option was added to set and get the TypedFieldMapper.
The old logic was moved into a class DefaultTypedFieldMapper which is used by default when no mapper is supplied.
The selected TypedFieldMapper is passed into ClassMetadataInfo constructor. If empty, the DefaultTypedFieldMapper is used.
There is also ChainTypedFieldMapper class which allows chaining multiple TypedFieldMappers and apply them in a cascade (always if a field gets type assigned by the earlier mapper in the list, it will not be changed later).

docs/en/index.rst

@@ -72,6 +72,7 @@ Advanced Topics
 * :doc:`Transactions and Concurrency <reference/transactions-and-concurrency>`
 * :doc:`Filters <reference/filters>`
 * :doc:`NamingStrategy <reference/namingstrategy>`
+* :doc:`TypedFieldMapper <reference/typedfieldmapper>`
 * :doc:`Improving Performance <reference/improving-performance>`
 * :doc:`Caching <reference/caching>`
 * :doc:`Partial Objects <reference/partial-objects>`

docs/en/reference/basic-mapping.rst

@@ -289,6 +289,13 @@ These are the "automatic" mapping rules:
 As of version 2.11 Doctrine can also automatically map typed properties using a
 PHP 8.1 enum to set the right ``type`` and ``enumType``.
 
+.. versionadded:: 2.14
+
+Since version 2.14 you can specify custom typed field mapping between PHP type and DBAL type using ``Configuration``
+and a custom ``Doctrine\ORM\Mapping\TypedFieldMapper`` implementation.
+
+:doc:`Read more about TypedFieldMapper <typedfieldmapper>`.
+
 .. _reference-mapping-types:
 
 Doctrine Mapping Types

docs/en/reference/typedfieldmapper.rst

@@ -0,0 +1,176 @@
+Implementing a TypedFieldMapper
+===============================
+
+.. versionadded:: 2.14
+
+You can specify custom typed field mapping between PHP type and DBAL type using ``Configuration``
+and a custom ``Doctrine\ORM\Mapping\TypedFieldMapper`` implementation.
+
+.. code-block:: php
+
+    <?php
+
+    $configuration->setTypedFieldMapper(new CustomTypedFieldMapper());
+
+
+DefaultTypedFieldMapper
+-----------------------
+
+By default the ``Doctrine\ORM\Mapping\DefaultTypedFieldMapper`` is used, and you can pass an array of
+PHP type => DBAL type mappings into its constructor to override the default behavior or add new mappings.
+
+.. code-block:: php
+
+    <?php
+    use App\CustomIds\CustomIdObject;
+    use App\DBAL\Type\CustomIdObjectType;
+
+    $configuration->setTypedFieldMapper(new DefaultTypedFieldMapper([
+        CustomIdObject::class => CustomIdObjectType::class,
+    ]));
+
+Then, an entity using the ``CustomIdObject`` typed field will be correctly assigned its DBAL type
+(``CustomIdObjectType``) without the need of explicit declaration.
+
+.. configuration-block::
+
+    .. code-block:: attribute
+
+        <?php
+        #[ORM\Entity]
+        #[ORM\Table(name: 'cms_users_typed_with_custom_typed_field')]
+        class UserTypedWithCustomTypedField
+        {
+            #[ORM\Column]
+            public CustomIdObject $customId;
+
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * @Entity
+         * @Table(name="cms_users_typed_with_custom_typed_field")
+         */
+        class UserTypedWithCustomTypedField
+        {
+            /** @Column */
+            public CustomIdObject $customId;
+
+            // ...
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="UserTypedWithCustomTypedField">
+            <field name="customId"/>
+            <!-- -->
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        UserTypedWithCustomTypedField:
+          type: entity
+          fields:
+            customId: ~
+
+It is perfectly valid to override even the "automatic" mapping rules mentioned above:
+
+.. code-block:: php
+
+    <?php
+    use App\DBAL\Type\CustomIntType;
+
+    $configuration->setTypedFieldMapper(new DefaultTypedFieldMapper([
+        'int' => CustomIntType::class,
+    ]));
+
+.. note::
+
+    If chained, once the first ``TypedFieldMapper`` assigns a type to a field, the ``DefaultTypedFieldMapper`` will
+    ignore its mapping and not override it anymore (if it is later in the chain). See below for chaining type mappers.
+
+
+TypedFieldMapper interface
+-------------------------
+The interface ``Doctrine\ORM\Mapping\TypedFieldMapper`` allows you to implement your own
+typed field mapping logic. It consists of just one function
+
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Validates & completes the given field mapping based on typed property.
+     *
+     * @param array{fieldName: string, enumType?: string, type?: mixed}  $mapping The field mapping to validate & complete.
+     * @param \ReflectionProperty                                        $field
+     *
+     * @return array{fieldName: string, enumType?: string, type?: mixed} The updated mapping.
+     */
+    public function validateAndComplete(array $mapping, ReflectionProperty $field): array;
+
+
+ChainTypedFieldMapper
+---------------------
+
+The class ``Doctrine\ORM\Mapping\ChainTypedFieldMapper`` allows you to chain multiple ``TypedFieldMapper`` instances.
+When being evaluated, the ``TypedFieldMapper::validateAndComplete`` is called in the order in which
+the instances were supplied to the ``ChainTypedFieldMapper`` constructor.
+
+.. code-block:: php
+
+    <?php
+    use App\DBAL\Type\CustomIntType;
+
+    $configuration->setTypedFieldMapper(
+        new ChainTypedFieldMapper(
+            DefaultTypedFieldMapper(['int' => CustomIntType::class,]),
+            new CustomTypedFieldMapper()
+        )
+    );
+
+
+Implementing a TypedFieldMapper
+-------------------------------
+
+If you want to assign all ``BackedEnum`` fields to your custom ``BackedEnumDBALType`` or you want to use different
+DBAL types based on whether the entity field is nullable or not, you can achieve this by implementing your own
+typed field mapper.
+
+You need to create a class which implements ``Doctrine\ORM\Mapping\TypedFieldMapper``.
+
+.. code-block:: php
+
+    <?php
+    final class CustomEnumTypedFieldMapper implements TypedFieldMapper
+    {
+        /**
+         * {@inheritdoc}
+         */
+        public function validateAndComplete(array $mapping, ReflectionProperty $field): array
+        {
+            $type = $field->getType();
+
+            if (
+                ! isset($mapping['type'])
+                && ($type instanceof ReflectionNamedType)
+            ) {
+                if (! $type->isBuiltin() && enum_exists($type->getName())) {
+                    $mapping['type'] = BackedEnumDBALType::class;
+                }
+            }
+
+            return $mapping;
+        }
+    }
+
+.. note::
+
+    Note that this case checks whether the mapping is already assigned, and if yes, it skips it. This is up to your
+    implementation. You can make a "greedy" mapper which will always override the mapping with its own type, or one
+    that behaves like ``DefaultTypedFieldMapper`` and does not modify the type once its set prior in the chain.

lib/Doctrine/ORM/Configuration.php

@@ -35,6 +35,7 @@
 use Doctrine\ORM\Mapping\EntityListenerResolver;
 use Doctrine\ORM\Mapping\NamingStrategy;
 use Doctrine\ORM\Mapping\QuoteStrategy;
+use Doctrine\ORM\Mapping\TypedFieldMapper;
 use Doctrine\ORM\Proxy\ProxyFactory;
 use Doctrine\ORM\Query\AST\Functions\FunctionNode;
 use Doctrine\ORM\Query\Filter\SQLFilter;
@@ -719,7 +720,7 @@ public function addCustomDatetimeFunction($name, $className)
      * @param string $name
      *
      * @return string|callable|null
-     * @psalm-return class-string|callable|null $name
+     * @psalm-return class-string|callable|null
      */
     public function getCustomDatetimeFunction($name)
     {
@@ -748,6 +749,22 @@ public function setCustomDatetimeFunctions(array $functions)
         }
     }
 
+    /**
+     * Sets a TypedFieldMapper for php typed fields to DBAL types auto-completion.
+     */
+    public function setTypedFieldMapper(?TypedFieldMapper $typedFieldMapper): void
+    {
+        $this->_attributes['typedFieldMapper'] = $typedFieldMapper;
+    }
+
+    /**
+     * Gets a TypedFieldMapper for php typed fields to DBAL types auto-completion.
+     */
+    public function getTypedFieldMapper(): ?TypedFieldMapper
+    {
+        return $this->_attributes['typedFieldMapper'] ?? null;
+    }
+
     /**
      * Sets the custom hydrator modes in one pass.
      *

lib/Doctrine/ORM/Mapping/ChainTypedFieldMapper.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Mapping;
+
+use ReflectionProperty;
+
+final class ChainTypedFieldMapper implements TypedFieldMapper
+{
+    /**
+     * @readonly
+     * @var TypedFieldMapper[] $typedFieldMappers
+     */
+    private array $typedFieldMappers;
+
+    public function __construct(TypedFieldMapper ...$typedFieldMappers)
+    {
+        $this->typedFieldMappers = $typedFieldMappers;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function validateAndComplete(array $mapping, ReflectionProperty $field): array
+    {
+        foreach ($this->typedFieldMappers as $typedFieldMapper) {
+            $mapping = $typedFieldMapper->validateAndComplete($mapping, $field);
+        }
+
+        return $mapping;
+    }
+}

lib/Doctrine/ORM/Mapping/ClassMetadata.php

@@ -21,8 +21,8 @@ class ClassMetadata extends ClassMetadataInfo
      * @param string $entityName The name of the entity class the new instance is used for.
      * @psalm-param class-string<T> $entityName
      */
-    public function __construct($entityName, ?NamingStrategy $namingStrategy = null)
+    public function __construct($entityName, ?NamingStrategy $namingStrategy = null, ?TypedFieldMapper $typedFieldMapper = null)
     {
-        parent::__construct($entityName, $namingStrategy);
+        parent::__construct($entityName, $namingStrategy, $typedFieldMapper);
     }
 }

lib/Doctrine/ORM/Mapping/ClassMetadataFactory.php

@@ -293,7 +293,11 @@ protected function validateRuntimeMetadata($class, $parent)
      */
     protected function newClassMetadataInstance($className)
     {
-        return new ClassMetadata($className, $this->em->getConfiguration()->getNamingStrategy());
+        return new ClassMetadata(
+            $className,
+            $this->em->getConfiguration()->getNamingStrategy(),
+            $this->em->getConfiguration()->getTypedFieldMapper()
+        );
     }
 
     /**