Add support for enum discriminator columns

This commit adds enumType option to DiscriminatorColumn as well as support for custom DBAL types which use PHP enums for PHP values. Previously, the enumType option was completely missing, but also even using custom types that used PHP enums would end up in exception because ObjectHydrator would try to convert enums to string using (string) explicit conversion. Apart from hydrators, ClassMetadataBuilder was extended to support specifying enumType. Documentation was updated.
doctrine · Dec 13, 2022 · 497ee16 · 497ee16
1 parent 284e814
commit 497ee16
Show file tree

Hide file tree

Showing 21 changed files with 410 additions and 11 deletions.
diff --git a/docs/en/reference/attributes-reference.rst b/docs/en/reference/attributes-reference.rst
@@ -366,6 +366,8 @@ Optional parameters:
 
 -  **type**: By default this is string.
 -  **length**: By default this is 255.
+-  **columnDefinition**: By default this is null the definition according to the type will be used. This option allows to override it.
+-  **enumType**: By default this is `null`. Allows to map discriminatorColumn value to PHP enum
 
 .. _attrref_discriminatormap:
 

diff --git a/docs/en/reference/php-mapping.rst b/docs/en/reference/php-mapping.rst
@@ -167,7 +167,7 @@ The API of the ClassMetadataBuilder has the following methods with a fluent inte
 -   ``addNamedQuery($name, $dqlQuery)``
 -   ``setJoinedTableInheritance()``
 -   ``setSingleTableInheritance()``
--   ``setDiscriminatorColumn($name, $type = 'string', $length = 255)``
+-   ``setDiscriminatorColumn($name, $type = 'string', $length = 255, $columnDefinition = null, $enumType = null)``
 -   ``addDiscriminatorMapClass($name, $class)``
 -   ``setChangeTrackingPolicyDeferredExplicit()``
 -   ``setChangeTrackingPolicyNotify()``

diff --git a/doctrine-mapping.xsd b/doctrine-mapping.xsd
@@ -337,6 +337,7 @@
     <xs:attribute name="field-name" type="xs:NMTOKEN" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="column-definition" type="xs:string" />
+    <xs:attribute name="enum-type" type="xs:string" />
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 

diff --git a/lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php b/lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php
@@ -617,6 +617,7 @@ protected function hydrateColumnInfo($key)
                     'fieldName'    => $fieldName,
                     'type'         => $type,
                     'dqlAlias'     => $dqlAlias,
+                    'enumType'     => $this->_rsm->enumMappings[$key] ?? null,
                 ];
         }
 

diff --git a/lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php b/lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php
@@ -4,6 +4,7 @@
 
 namespace Doctrine\ORM\Internal\Hydration;
 
+use BackedEnum;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\PersistentCollection;
@@ -246,7 +247,12 @@ private function getEntity(array $data, string $dqlAlias)
             }
 
             $discrMap           = $this->_metadataCache[$className]->discriminatorMap;
-            $discriminatorValue = (string) $data[$discrColumn];
+            $discriminatorValue = $data[$discrColumn];
+            if ($discriminatorValue instanceof BackedEnum) {
+                $discriminatorValue = $discriminatorValue->value;
+            }
+
+            $discriminatorValue = (string) $discriminatorValue;
 
             if (! isset($discrMap[$discriminatorValue])) {
                 throw HydrationException::invalidDiscriminatorValue($discriminatorValue, array_keys($discrMap));

diff --git a/lib/Doctrine/ORM/Mapping/Builder/ClassMetadataBuilder.php b/lib/Doctrine/ORM/Mapping/Builder/ClassMetadataBuilder.php
@@ -4,6 +4,7 @@
 
 namespace Doctrine\ORM\Mapping\Builder;
 
+use BackedEnum;
 use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Mapping\ClassMetadataInfo;
@@ -218,16 +219,19 @@ public function setSingleTableInheritance()
      * @param string $name
      * @param string $type
      * @param int    $length
+     * @psalm-param class-string<BackedEnum>|null $enumType
      *
      * @return $this
      */
-    public function setDiscriminatorColumn($name, $type = 'string', $length = 255)
+    public function setDiscriminatorColumn($name, $type = 'string', $length = 255, ?string $columnDefinition = null, ?string $enumType = null)
     {
         $this->cm->setDiscriminatorColumn(
             [
                 'name' => $name,
                 'type' => $type,
                 'length' => $length,
+                'columnDefinition' => $columnDefinition,
+                'enumType' => $enumType,
             ]
         );
 

diff --git a/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php b/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php
@@ -574,7 +574,7 @@ class ClassMetadataInfo implements ClassMetadata
      * READ-ONLY: The definition of the discriminator column used in JOINED and SINGLE_TABLE
      * inheritance mappings.
      *
-     * @psalm-var array{name: string, fieldName: string, type: string, length?: int, columnDefinition?: string|null}|null
+     * @psalm-var array{name: string, fieldName: string, type: string, length?: int, columnDefinition?: string|null, enumType?: class-string<BackedEnum>|null}|null
      */
     public $discriminatorColumn;
 
@@ -3220,7 +3220,7 @@ public function addEntityListener($eventName, $class, $method)
      * @see getDiscriminatorColumn()
      *
      * @param mixed[]|null $columnDef
-     * @psalm-param array{name: string|null, fieldName?: string, type?: string, length?: int, columnDefinition?: string|null}|null $columnDef
+     * @psalm-param array{name: string|null, fieldName?: string, type?: string, length?: int, columnDefinition?: string|null, enumType?: class-string<BackedEnum>|null}|null $columnDef
      *
      * @return void
      *

diff --git a/lib/Doctrine/ORM/Mapping/DiscriminatorColumn.php b/lib/Doctrine/ORM/Mapping/DiscriminatorColumn.php
@@ -39,15 +39,24 @@ final class DiscriminatorColumn implements MappingAttribute
      */
     public $columnDefinition;
 
+    /**
+     * @var class-string<\BackedEnum>|null
+     * @readonly
+     */
+    public $enumType = null;
+
+    /** @param class-string<\BackedEnum>|null $enumType */
     public function __construct(
         ?string $name = null,
         ?string $type = null,
         ?int $length = null,
-        ?string $columnDefinition = null
+        ?string $columnDefinition = null,
+        ?string $enumType = null
     ) {
         $this->name             = $name;
         $this->type             = $type;
         $this->length           = $length;
         $this->columnDefinition = $columnDefinition;
+        $this->enumType         = $enumType;
     }
 }
diff --git a/lib/Doctrine/ORM/Mapping/Driver/AnnotationDriver.php b/lib/Doctrine/ORM/Mapping/Driver/AnnotationDriver.php
@@ -319,6 +319,7 @@ public function loadMetadataForClass($className, PersistenceClassMetadata $metad
                             'type'             => $discrColumnAnnot->type ?: 'string',
                             'length'           => $discrColumnAnnot->length ?? 255,
                             'columnDefinition' => $discrColumnAnnot->columnDefinition,
+                            'enumType'         => $discrColumnAnnot->enumType,
                         ]
                     );
                 } else {

diff --git a/lib/Doctrine/ORM/Mapping/Driver/AttributeDriver.php b/lib/Doctrine/ORM/Mapping/Driver/AttributeDriver.php
@@ -271,6 +271,7 @@ public function loadMetadataForClass($className, PersistenceClassMetadata $metad
                             'type'             => isset($discrColumnAttribute->type) ? (string) $discrColumnAttribute->type : 'string',
                             'length'           => isset($discrColumnAttribute->length) ? (int) $discrColumnAttribute->length : 255,
                             'columnDefinition' => isset($discrColumnAttribute->columnDefinition) ? (string) $discrColumnAttribute->columnDefinition : null,
+                            'enumType'         => isset($discrColumnAttribute->enumType) ? (string) $discrColumnAttribute->enumType : null,
                         ]
                     );
                 } else {

diff --git a/lib/Doctrine/ORM/Mapping/Driver/XmlDriver.php b/lib/Doctrine/ORM/Mapping/Driver/XmlDriver.php
@@ -210,6 +210,7 @@ public function loadMetadataForClass($className, PersistenceClassMetadata $metad
                             'type' => isset($discrColumn['type']) ? (string) $discrColumn['type'] : 'string',
                             'length' => isset($discrColumn['length']) ? (int) $discrColumn['length'] : 255,
                             'columnDefinition' => isset($discrColumn['column-definition']) ? (string) $discrColumn['column-definition'] : null,
+                            'enumType' => isset($discrColumn['enum-type']) ? (string) $discrColumn['enum-type'] : null,
                         ]
                     );
                 } else {

diff --git a/lib/Doctrine/ORM/Mapping/Driver/YamlDriver.php b/lib/Doctrine/ORM/Mapping/Driver/YamlDriver.php
@@ -201,6 +201,7 @@ public function loadMetadataForClass($className, PersistenceClassMetadata $metad
                             'type' => isset($discrColumn['type']) ? (string) $discrColumn['type'] : 'string',
                             'length' => isset($discrColumn['length']) ? (int) $discrColumn['length'] : 255,
                             'columnDefinition' => isset($discrColumn['columnDefinition']) ? (string) $discrColumn['columnDefinition'] : null,
+                            'enumType' => isset($discrColumn['enumType']) ? (string) $discrColumn['enumType'] : null,
                         ]
                     );
                 } else {

diff --git a/lib/Doctrine/ORM/Query/SqlWalker.php b/lib/Doctrine/ORM/Query/SqlWalker.php
@@ -775,6 +775,9 @@ public function walkSelectClause($selectClause)
 
                 $this->rsm->setDiscriminatorColumn($dqlAlias, $columnAlias);
                 $this->rsm->addMetaResult($dqlAlias, $columnAlias, $discrColumn['fieldName'], false, $discrColumn['type']);
+                if (! empty($discrColumn['enumType'])) {
+                    $this->rsm->addEnumResult($columnAlias, $discrColumn['enumType']);
+                }
             }
 
             // Add foreign key columns to SQL, if necessary

diff --git a/psalm-baseline.xml b/psalm-baseline.xml
@@ -785,7 +785,7 @@
     </UndefinedInterfaceMethod>
   </file>
   <file src="lib/Doctrine/ORM/Mapping/Driver/AttributeDriver.php">
-    <InvalidArgument occurrences="1"/>
+    <InvalidArgument occurrences="2"/>
     <InvalidArrayAccess occurrences="4">
       <code>$value[0]</code>
       <code>$value[0]</code>
@@ -865,7 +865,7 @@
       <code>addNamedNativeQuery</code>
       <code>addNamedQuery</code>
     </DeprecatedMethod>
-    <InvalidArgument occurrences="4">
+    <InvalidArgument occurrences="5">
       <code>$this-&gt;cacheToArray($manyToManyElement-&gt;cache)</code>
       <code>$this-&gt;cacheToArray($manyToOneElement-&gt;cache)</code>
       <code>$this-&gt;cacheToArray($oneToManyElement-&gt;cache)</code>
@@ -931,6 +931,7 @@
       <code>addNamedNativeQuery</code>
       <code>addNamedQuery</code>
     </DeprecatedMethod>
+    <InvalidArgument occurrences="1"/>
     <InvalidDocblock occurrences="1">
       <code>private function cacheToArray(array $cacheMapping): array</code>
     </InvalidDocblock>

diff --git a/tests/Doctrine/Tests/Models/GH10288/GH10288People.php b/tests/Doctrine/Tests/Models/GH10288/GH10288People.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\Models\GH10288;
+
+enum GH10288People: string
+{
+    case BOSS     = 'boss';
+    case EMPLOYEE = 'employee';
+}