Merge pull request #11946 from doctrine/3.3.x

Merge 3.3.x up into 3.4.x

Author: greg0ire

docs/en/cookbook/generated-columns.rst

@@ -0,0 +1,44 @@
+Generated Columns
+=================
+
+Generated columns, sometimes also called virtual columns, are populated by
+the database engine itself. They are a tool for performance optimization, to
+avoid calculating a value on each query.
+
+You can define generated columns on entities and have Doctrine map the values
+to your entity.
+
+Declaring a generated column
+----------------------------
+
+There is no explicit mapping instruction for generated columns. Instead, you
+specify that the column should not be written to, and define a custom column
+definition.
+
+.. code-block:: php
+    .. literalinclude:: generated-columns/Person.php
+
+* ``insertable``, ``updatable``: Setting these to false tells Doctrine to never
+  write this column - writing to a generated column would result in an error
+  from the database.
+* ``columnDefinition``: We specify the full DDL to create the column. To allow
+  to use database specific features, this attribute does not use Doctrine Query
+  Language but native SQL. Note that you need to reference columns by their
+  database name (either explicitly set in the mapping or per the current
+  :doc:`naming strategy <../reference/namingstrategy>`).
+  Be aware that specifying a column definition makes the ``SchemaTool``
+  completely ignore all other configuration for this column. See also
+  :ref:`#[Column] <attrref_column>`
+* ``generated``: Specifying that this column is always generated tells Doctrine
+  to update the field on the entity with the value from the database after
+  every write operation.
+
+Advanced example: Extracting a value from a JSON structure
+----------------------------------------------------------
+
+Lets assume we have an entity that stores a blogpost as structured JSON.
+To avoid extracting all titles on the fly when listing the posts, we create a
+generated column with the field.
+
+.. code-block:: php
+    .. literalinclude:: generated-columns/Article.php

docs/en/cookbook/generated-columns/Article.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class Article
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private int $id;
+
+    /**
+     * When working with Postgres, it is recommended to use the jsonb
+     * format for better performance.
+     */
+    #[ORM\Column(options: ['jsonb' => true])]
+    private array $content;
+
+    /**
+     * Because we specify NOT NULL, inserting will fail if the content does
+     * not have a string in the title field.
+     */
+    #[ORM\Column(
+        insertable: false,
+        updatable: false,
+        columnDefinition: "VARCHAR(255) generated always as (content->>'title') stored NOT NULL",
+        generated: 'ALWAYS',
+    )]
+    private string $title;
+}

docs/en/cookbook/generated-columns/Person.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class Person
+{
+    #[ORM\Column(type: 'string')]
+    private string $firstName;
+
+    #[ORM\Column(type: 'string', name: 'name')]
+    private string $lastName;
+
+    #[ORM\Column(
+        type: 'string',
+        insertable: false,
+        updatable: false,
+        columnDefinition: "VARCHAR(255) GENERATED ALWAYS AS (concat(firstName, ' ', name) stored NOT NULL",
+        generated: 'ALWAYS',
+    )]
+    private string $fullName;
+}

docs/en/index.rst

@@ -102,6 +102,7 @@ Cookbook
 
 * **Patterns**:
   :doc:`Aggregate Fields <cookbook/aggregate-fields>` \|
+  :doc:`Generated/Virtual Columns <cookbook/generated-columns>` \|
   :doc:`Decorator Pattern <cookbook/decorator-pattern>` \|
   :doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>`
 
@@ -121,4 +122,5 @@ Cookbook
 
 * **Custom Datatypes**
   :doc:`MySQL Enums <cookbook/mysql-enums>`
+  :doc:`Custom Mapping Types <cookbook/custom-mapping-types>`
   :doc:`Advanced Field Value Conversion <cookbook/advanced-field-value-conversion-using-custom-mapping-types>`

docs/en/reference/attributes-reference.rst

@@ -214,12 +214,15 @@ Optional parameters:
    -  ``check``: Adds a check constraint type to the column (might not
       be supported by all vendors).
 
--  **columnDefinition**: DDL SQL snippet that starts after the column
+-  **columnDefinition**: Specify the DDL SQL snippet that starts after the column
    name and specifies the complete (non-portable!) column definition.
    This attribute allows to make use of advanced RMDBS features.
-   However you should make careful use of this feature and the
-   consequences. ``SchemaTool`` will not detect changes on the column correctly
-   anymore if you use ``columnDefinition``.
+   However, as this needs to be specified in the DDL native to the database,
+   the resulting schema changes are no longer portable. If you specify a
+   ``columnDefinition``, the ``SchemaTool`` ignores all other attributes
+   that are normally used to build the definition DDL. Changes to the
+   ``columnDefinition`` are not detected, you will need to manually create a
+   migration to apply changes.
 
    Additionally you should remember that the ``type``
    attribute still handles the conversion between PHP and Database
@@ -262,10 +265,11 @@ Examples:
     )]
     protected $loginCount;
 
-    // MySQL example: full_name char(41) GENERATED ALWAYS AS (concat(firstname,' ',lastname)),
+    // columnDefinition is raw SQL, not DQL. This example works for MySQL:
     #[Column(
         type: "string",
         name: "user_fullname",
+        columnDefinition: "VARCHAR(255) GENERATED ALWAYS AS (concat(firstname,' ',lastname))",
         insertable: false,
         updatable: false
     )]
@@ -366,7 +370,7 @@ 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.
+-  **columnDefinition**: Allows to override how the column is generated. See the "columnDefinition" attribute on :ref:`#[Column] <attrref_column>`
 -  **enumType**: By default this is `null`. Allows to map discriminatorColumn value to PHP enum
 -  **options**: See "options" attribute on :ref:`#[Column] <attrref_column>`.
 
@@ -678,8 +682,10 @@ Optional parameters:
 -  **onDelete**: Cascade Action (Database-level)
 -  **columnDefinition**: DDL SQL snippet that starts after the column
    name and specifies the complete (non-portable!) column definition.
-   This attribute enables the use of advanced RMDBS features. Using
-   this attribute on ``#[JoinColumn]`` is necessary if you need slightly
+   This attribute enables the use of advanced RMDBS features. Note that you
+   need to reference columns by their database name (either explicitly set in
+   the mapping or per the current :doc:`naming strategy <namingstrategy>`).
+   Using this attribute on ``#[JoinColumn]`` is necessary if you need
    different column definitions for joining columns, for example
    regarding NULL/NOT NULL defaults. However by default a
    "columnDefinition" attribute on :ref:`#[Column] <attrref_column>` also sets
@@ -1134,7 +1140,7 @@ Marker attribute that defines a specified column as version attribute used in
 an :ref:`optimistic locking <transactions-and-concurrency_optimistic-locking>`
 scenario. It only works on :ref:`#[Column] <attrref_column>` attributes that have
 the type ``integer`` or ``datetime``. Setting ``#[Version]`` on a property with
-:ref:`#[Id <attrref_id>` is not supported.
+:ref:`#[Id] <attrref_id>` is not supported.
 
 Example:
 

docs/en/sidebar.rst

@@ -64,6 +64,7 @@
    cookbook/decorator-pattern
    cookbook/dql-custom-walkers
    cookbook/dql-user-defined-functions
+   cookbook/generated-columns
    cookbook/implementing-arrayaccess-for-domain-objects
    cookbook/resolve-target-entity-listener
    cookbook/sql-table-prefixes

src/Persisters/Entity/BasicEntityPersister.php

@@ -201,6 +201,16 @@ public function __construct(
         );
     }
 
+    final protected function isFilterHashUpToDate(): bool
+    {
+        return $this->filterHash === $this->em->getFilters()->getHash();
+    }
+
+    final protected function updateFilterHash(): void
+    {
+        $this->filterHash = $this->em->getFilters()->getHash();
+    }
+
     public function getClassMetadata(): ClassMetadata
     {
         return $this->class;
@@ -1231,7 +1241,7 @@ final protected function getOrderBySQL(array $orderBy, string $baseTableAlias):
      */
     protected function getSelectColumnsSQL(): string
     {
-        if ($this->currentPersisterContext->selectColumnListSql !== null && $this->filterHash === $this->em->getFilters()->getHash()) {
+        if ($this->currentPersisterContext->selectColumnListSql !== null && $this->isFilterHashUpToDate()) {
             return $this->currentPersisterContext->selectColumnListSql;
         }
 
@@ -1347,7 +1357,7 @@ protected function getSelectColumnsSQL(): string
         }
 
         $this->currentPersisterContext->selectColumnListSql = implode(', ', $columnList);
-        $this->filterHash                                   = $this->em->getFilters()->getHash();
+        $this->updateFilterHash();
 
         return $this->currentPersisterContext->selectColumnListSql;
     }

src/Persisters/Entity/JoinedSubclassPersister.php

@@ -358,7 +358,7 @@ protected function getLockTablesSql(LockMode|int $lockMode): string
     protected function getSelectColumnsSQL(): string
     {
         // Create the column list fragment only once
-        if ($this->currentPersisterContext->selectColumnListSql !== null) {
+        if ($this->currentPersisterContext->selectColumnListSql !== null && $this->isFilterHashUpToDate()) {
             return $this->currentPersisterContext->selectColumnListSql;
         }
 
@@ -445,6 +445,7 @@ protected function getSelectColumnsSQL(): string
         }
 
         $this->currentPersisterContext->selectColumnListSql = implode(', ', $columnList);
+        $this->updateFilterHash();
 
         return $this->currentPersisterContext->selectColumnListSql;
     }

src/Persisters/Entity/SingleTablePersister.php

@@ -35,7 +35,7 @@ protected function getDiscriminatorColumnTableName(): string
     protected function getSelectColumnsSQL(): string
     {
         $columnList = [];
-        if ($this->currentPersisterContext->selectColumnListSql !== null) {
+        if ($this->currentPersisterContext->selectColumnListSql !== null && $this->isFilterHashUpToDate()) {
             return $this->currentPersisterContext->selectColumnListSql;
         }
 
@@ -89,6 +89,7 @@ protected function getSelectColumnsSQL(): string
         }
 
         $this->currentPersisterContext->selectColumnListSql = implode(', ', $columnList);
+        $this->updateFilterHash();
 
         return $this->currentPersisterContext->selectColumnListSql;
     }

tests/Tests/ORM/Functional/Ticket/SwitchContextWithFilter/AbstractTestCase.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\ORM\Functional\Ticket\SwitchContextWithFilter;
+
+use Doctrine\Tests\OrmFunctionalTestCase;
+
+use function sprintf;
+use function str_replace;
+
+abstract class AbstractTestCase extends OrmFunctionalTestCase
+{
+    protected function generateMessage(string $message): string
+    {
+        $log = $this->getLastLoggedQuery();
+
+        return sprintf("%s\nSQL: %s", $message, str_replace(['?'], (array) $log['params'], $log['sql']));
+    }
+
+    protected function clearCachedData(object ...$entities): void
+    {
+        foreach ($entities as $entity) {
+            $this->_em->refresh($entity);
+        }
+    }
+
+    protected function persistFlushClear(object ...$entities): void
+    {
+        foreach ($entities as $entity) {
+            $this->_em->persist($entity);
+        }
+
+        $this->_em->flush();
+        $this->_em->clear();
+    }
+}

tests/Tests/ORM/Functional/Ticket/SwitchContextWithFilter/ChangeFiltersTest.php

@@ -4,12 +4,11 @@
 
 namespace Doctrine\Tests\ORM\Functional\Ticket\SwitchContextWithFilter;
 
-use Doctrine\Tests\OrmFunctionalTestCase;
+use Doctrine\Tests\ORM\Functional\Ticket\SwitchContextWithFilter\Entity\Order;
+use Doctrine\Tests\ORM\Functional\Ticket\SwitchContextWithFilter\Entity\User;
+use Doctrine\Tests\ORM\Functional\Ticket\SwitchContextWithFilter\SQLFilter\CompanySQLFilter;
 
-use function sprintf;
-use function str_replace;
-
-final class ChangeFiltersTest extends OrmFunctionalTestCase
+final class ChangeFiltersTest extends AbstractTestCase
 {
     private const COMPANY_A = 'A';
     private const COMPANY_B = 'B';
@@ -130,11 +129,4 @@ public function testUseQueryBuilder(): void
         self::assertInstanceOf(User::class, $order->user);
         self::assertEquals($companyB['userId'], $order->user->id);
     }
-
-    private function generateMessage(string $message): string
-    {
-        $log = $this->getLastLoggedQuery();
-
-        return sprintf("%s\nSQL: %s", $message, str_replace(['?'], (array) $log['params'], $log['sql']));
-    }
 }

tests/Tests/ORM/Functional/Ticket/SwitchContextWithFilter/Entity/Insurance.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\ORM\Functional\Ticket\SwitchContextWithFilter\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class Insurance
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: 'integer')]
+    public int $id;
+
+    #[ORM\Column(type: 'string')]
+    public string $name;
+
+    #[ORM\ManyToOne(targetEntity: Practice::class)]
+    public Practice $practice;
+
+    public function __construct(Practice $practice, string $name)
+    {
+        $this->practice = $practice;
+        $this->name     = $name;
+    }
+}

tests/Tests/ORM/Functional/Ticket/SwitchContextWithFilter/Order.php renamed to tests/Tests/ORM/Functional/Ticket/SwitchContextWithFilter/Entity/Order.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Doctrine\Tests\ORM\Functional\Ticket\SwitchContextWithFilter;
+namespace Doctrine\Tests\ORM\Functional\Ticket\SwitchContextWithFilter\Entity;
 
 use Doctrine\ORM\Mapping as ORM;