Generated/Virtual Columns: Insertable / Updateable (#9118)

* Generated/Virtual Columns: Insertable / Updateable

Defines whether a column is included in an SQL INSERT and/or UPDATE statement.
Throws an exception for UPDATE statements attempting to update this field/column.

Closes #5728

* Apply suggestions from code review

Co-authored-by: Grégoire Paris <[email protected]>

* Add example for virtual column usage in attributes to docs.

Co-authored-by: Benjamin Eberlei <[email protected]>
Co-authored-by: Grégoire Paris <[email protected]>

Author: 3 people

docs/en/reference/annotations-reference.rst

@@ -123,6 +123,18 @@ Optional attributes:
 
 -  **nullable**: Determines if NULL values allowed for this column. If not specified, default value is false.
 
+-  **insertable**: Boolean value to determine if the column should be
+   included when inserting a new row into the underlying entities table. 
+   If not specified, default value is true.
+
+-  **updatable**: Boolean value to determine if the column should be
+   included when updating the row of the underlying entities table.
+   If not specified, default value is true.
+
+-  **generated**: An enum with the possible values ALWAYS, INSERT, NEVER.  Is
+   used after an INSERT or UPDATE statement to determine if the database
+   generated this value and it needs to be fetched using a SELECT statement.
+
 -  **options**: Array of additional options:
 
    -  ``default``: The default value to set for the column if no value
@@ -193,6 +205,13 @@ Examples:
      */
     protected $loginCount;
 
+    /**
+     * Generated column
+     * @Column(type="string", name="user_fullname", insertable=false, updatable=false)
+     * MySQL example: full_name char(41) GENERATED ALWAYS AS (concat(firstname,' ',lastname)),
+     */
+    protected $fullname;
+
 .. _annref_column_result:
 
 @ColumnResult

docs/en/reference/attributes-reference.rst

@@ -178,6 +178,18 @@ Optional parameters:
 -  **nullable**: Determines if NULL values allowed for this column.
     If not specified, default value is ``false``.
 
+-  **insertable**: Boolean value to determine if the column should be
+   included when inserting a new row into the underlying entities table. 
+   If not specified, default value is true.
+
+-  **updatable**: Boolean value to determine if the column should be
+   included when updating the row of the underlying entities table.
+   If not specified, default value is true.
+
+-  **generated**: An enum with the possible values ALWAYS, INSERT, NEVER.  Is
+   used after an INSERT or UPDATE statement to determine if the database
+   generated this value and it needs to be fetched using a SELECT statement.
+
 -  **options**: Array of additional options:
 
    -  ``default``: The default value to set for the column if no value
@@ -248,6 +260,15 @@ Examples:
     )]
     protected $loginCount;
 
+    // MySQL example: full_name char(41) GENERATED ALWAYS AS (concat(firstname,' ',lastname)),
+    #[Column(
+        type: "string",
+        name: "user_fullname",
+        insertable: false,
+        updatable: false
+    )]
+    protected $fullname;
+
 .. _attrref_cache:
 
 #[Cache]

docs/en/reference/basic-mapping.rst

@@ -199,6 +199,10 @@ list:
   unique key.
 - ``nullable``: (optional, default FALSE) Whether the database
   column is nullable.
+- ``insertable``: (optional, default TRUE) Whether the database
+  column should be inserted.
+- ``updatable``: (optional, default TRUE) Whether the database
+  column should be updated.
 - ``enumType``: (optional, requires PHP 8.1 and ORM 2.11) The PHP enum type
   name to convert the database value into.
 - ``precision``: (optional, default 0) The precision for a decimal

docs/en/reference/xml-mapping.rst

@@ -256,6 +256,11 @@ Optional attributes:
    table? Defaults to false.
 -  nullable - Should this field allow NULL as a value? Defaults to
    false.
+-  insertable - Should this field be inserted? Defaults to true.
+-  updatable - Should this field be updated? Defaults to true.
+-  generated - Enum of the values ALWAYS, INSERT, NEVER that determines if
+   generated value must be fetched from database after INSERT or UPDATE.
+   Defaults to "NEVER".
 -  version - Should this field be used for optimistic locking? Only
    works on fields with type integer or datetime.
 -  scale - Scale of a decimal type.

doctrine-mapping.xsd

@@ -288,6 +288,14 @@
     </xs:restriction>
   </xs:simpleType>
 
+  <xs:simpleType name="generated-type">
+    <xs:restriction base="xs:token">
+      <xs:enumeration value="NEVER"/>
+      <xs:enumeration value="INSERT"/>
+      <xs:enumeration value="ALWAYS"/>
+    </xs:restriction>
+  </xs:simpleType>
+
   <xs:complexType name="field">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
@@ -299,6 +307,9 @@
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <xs:attribute name="nullable" type="xs:boolean" default="false" />
+    <xs:attribute name="insertable" type="xs:boolean" default="true" />
+    <xs:attribute name="updatable" type="xs:boolean" default="true" />
+    <xs:attribute name="generated" type="orm:generated-type" default="NEVER" />
     <xs:attribute name="enum-type" type="xs:string" />
     <xs:attribute name="version" type="xs:boolean" />
     <xs:attribute name="column-definition" type="xs:string" />
@@ -623,6 +634,8 @@
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <xs:attribute name="nullable" type="xs:boolean" default="false" />
+    <xs:attribute name="insertable" type="xs:boolean" default="true" />
+    <xs:attribute name="updateable" type="xs:boolean" default="true" />
     <xs:attribute name="version" type="xs:boolean" />
     <xs:attribute name="column-definition" type="xs:string" />
     <xs:attribute name="precision" type="xs:integer" use="optional" />

lib/Doctrine/ORM/Cache/DefaultEntityHydrator.php

@@ -55,8 +55,16 @@ public function buildCacheEntry(ClassMetadata $metadata, EntityCacheKey $key, $e
         $data = $this->uow->getOriginalEntityData($entity);
         $data = array_merge($data, $metadata->getIdentifierValues($entity)); // why update has no identifier values ?
 
-        if ($metadata->isVersioned) {
-            $data[$metadata->versionField] = $metadata->getFieldValue($entity, $metadata->versionField);
+        if ($metadata->requiresFetchAfterChange) {
+            if ($metadata->isVersioned) {
+                $data[$metadata->versionField] = $metadata->getFieldValue($entity, $metadata->versionField);
+            }
+
+            foreach ($metadata->fieldMappings as $name => $fieldMapping) {
+                if (isset($fieldMapping['generated'])) {
+                    $data[$name] = $metadata->getFieldValue($entity, $name);
+                }
+            }
         }
 
         foreach ($metadata->associationMappings as $name => $assoc) {

lib/Doctrine/ORM/Mapping/Builder/FieldBuilder.php

@@ -110,6 +110,34 @@ public function precision($p)
         return $this;
     }
 
+    /**
+     * Sets insertable.
+     *
+     * @return $this
+     */
+    public function insertable(bool $flag = true): self
+    {
+        if (! $flag) {
+            $this->mapping['notInsertable'] = true;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Sets updatable.
+     *
+     * @return $this
+     */
+    public function updatable(bool $flag = true): self
+    {
+        if (! $flag) {
+            $this->mapping['notUpdatable'] = true;
+        }
+
+        return $this;
+    }
+
     /**
      * Sets scale.
      *

lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php

@@ -80,6 +80,9 @@
  *      length?: int,
  *      id?: bool,
  *      nullable?: bool,
+ *      notInsertable?: bool,
+ *      notUpdatable?: bool,
+ *      generated?: string,
  *      enumType?: class-string<BackedEnum>,
  *      columnDefinition?: string,
  *      precision?: int,
@@ -258,6 +261,21 @@ class ClassMetadataInfo implements ClassMetadata
      */
     public const CACHE_USAGE_READ_WRITE = 3;
 
+    /**
+     * The value of this column is never generated by the database.
+     */
+    public const GENERATED_NEVER = 0;
+
+    /**
+     * The value of this column is generated by the database on INSERT, but not on UPDATE.
+     */
+    public const GENERATED_INSERT = 1;
+
+    /**
+     * The value of this column is generated by the database on both INSERT and UDPATE statements.
+     */
+    public const GENERATED_ALWAYS = 2;
+
     /**
      * READ-ONLY: The name of the entity class.
      *
@@ -439,6 +457,12 @@ class ClassMetadataInfo implements ClassMetadata
      * - <b>nullable</b> (boolean, optional)
      * Whether the column is nullable. Defaults to FALSE.
      *
+     * - <b>'notInsertable'</b> (boolean, optional)
+     * Whether the column is not insertable. Optional. Is only set if value is TRUE.
+     *
+     * - <b>'notUpdatable'</b> (boolean, optional)
+     * Whether the column is updatable. Optional. Is only set if value is TRUE.
+     *
      * - <b>columnDefinition</b> (string, optional, schema-only)
      * The SQL fragment that is used when generating the DDL for the column.
      *
@@ -659,13 +683,21 @@ class ClassMetadataInfo implements ClassMetadata
      */
     public $changeTrackingPolicy = self::CHANGETRACKING_DEFERRED_IMPLICIT;
 
+    /**
+     * READ-ONLY: A Flag indicating whether one or more columns of this class
+     * have to be reloaded after insert / update operations.
+     *
+     * @var bool
+     */
+    public $requiresFetchAfterChange = false;
+
     /**
      * READ-ONLY: A flag for whether or not instances of this class are to be versioned
      * with optimistic locking.
      *
      * @var bool
      */
-    public $isVersioned;
+    public $isVersioned = false;
 
     /**
      * READ-ONLY: The name of the field which is used for versioning in optimistic locking (if any).
@@ -963,6 +995,10 @@ public function __sleep()
             $serialized[] = 'cache';
         }
 
+        if ($this->requiresFetchAfterChange) {
+            $serialized[] = 'requiresFetchAfterChange';
+        }
+
         return $serialized;
     }
 
@@ -1611,6 +1647,16 @@ protected function validateAndCompleteFieldMapping(array $mapping): array
             $mapping['requireSQLConversion'] = true;
         }
 
+        if (isset($mapping['generated'])) {
+            if (! in_array($mapping['generated'], [self::GENERATED_NEVER, self::GENERATED_INSERT, self::GENERATED_ALWAYS])) {
+                throw MappingException::invalidGeneratedMode($mapping['generated']);
+            }
+
+            if ($mapping['generated'] === self::GENERATED_NEVER) {
+                unset($mapping['generated']);
+            }
+        }
+
         if (isset($mapping['enumType'])) {
             if (PHP_VERSION_ID < 80100) {
                 throw MappingException::enumsRequirePhp81($this->name, $mapping['fieldName']);
@@ -2675,6 +2721,10 @@ public function mapField(array $mapping)
         $mapping = $this->validateAndCompleteFieldMapping($mapping);
         $this->assertFieldNotMapped($mapping['fieldName']);
 
+        if (isset($mapping['generated'])) {
+            $this->requiresFetchAfterChange = true;
+        }
+
         $this->fieldMappings[$mapping['fieldName']] = $mapping;
     }
 
@@ -3405,8 +3455,9 @@ public function setSequenceGeneratorDefinition(array $definition)
      */
     public function setVersionMapping(array &$mapping)
     {
-        $this->isVersioned  = true;
-        $this->versionField = $mapping['fieldName'];
+        $this->isVersioned              = true;
+        $this->versionField             = $mapping['fieldName'];
+        $this->requiresFetchAfterChange = true;
 
         if (! isset($mapping['default'])) {
             if (in_array($mapping['type'], ['integer', 'bigint', 'smallint'], true)) {
@@ -3429,6 +3480,10 @@ public function setVersionMapping(array &$mapping)
     public function setVersioned($bool)
     {
         $this->isVersioned = $bool;
+
+        if ($bool) {
+            $this->requiresFetchAfterChange = true;
+        }
     }
 
     /**

lib/Doctrine/ORM/Mapping/Column.php

@@ -44,6 +44,12 @@ final class Column implements Annotation
     /** @var bool */
     public $nullable = false;
 
+    /** @var bool */
+    public $insertable = true;
+
+    /** @var bool */
+    public $updatable = true;
+
     /** @var class-string<\BackedEnum>|null */
     public $enumType = null;
 
@@ -53,9 +59,17 @@ final class Column implements Annotation
     /** @var string|null */
     public $columnDefinition;
 
+    /**
+     * @var string|null
+     * @psalm-var 'NEVER'|'INSERT'|'ALWAYS'|null
+     * @Enum({"NEVER", "INSERT", "ALWAYS"})
+     */
+    public $generated;
+
     /**
      * @param class-string<\BackedEnum>|null $enumType
      * @param array<string,mixed>            $options
+     * @psalm-param 'NEVER'|'INSERT'|'ALWAYS'|null $generated
      */
     public function __construct(
         ?string $name = null,
@@ -65,9 +79,12 @@ public function __construct(
         ?int $scale = null,
         bool $unique = false,
         bool $nullable = false,
+        bool $insertable = true,
+        bool $updatable = true,
         ?string $enumType = null,
         array $options = [],
-        ?string $columnDefinition = null
+        ?string $columnDefinition = null,
+        ?string $generated = null
     ) {
         $this->name             = $name;
         $this->type             = $type;
@@ -76,8 +93,11 @@ public function __construct(
         $this->scale            = $scale;
         $this->unique           = $unique;
         $this->nullable         = $nullable;
+        $this->insertable       = $insertable;
+        $this->updatable        = $updatable;
         $this->enumType         = $enumType;
         $this->options          = $options;
         $this->columnDefinition = $columnDefinition;
+        $this->generated        = $generated;
     }
 }