Merge origin/2.17.x into 3.0.x (using imerge)

.doctrine-project.json

@@ -12,21 +12,27 @@
             "upcoming": true
         },
         {
-            "name": "2.16",
-            "branchName": "2.16.x",
-            "slug": "2.16",
+            "name": "2.17",
+            "branchName": "2.17.x",
+            "slug": "2.17",
             "upcoming": true
         },
         {
-            "name": "2.15",
-            "branchName": "2.15.x",
-            "slug": "2.15",
+            "name": "2.16",
+            "branchName": "2.16.x",
+            "slug": "2.16",
             "current": true,
             "aliases": [
                 "current",
                 "stable"
             ]
         },
+        {
+            "name": "2.15",
+            "branchName": "2.15.x",
+            "slug": "2.15",
+            "maintained": false
+        },
         {
             "name": "2.14",
             "branchName": "2.14.x",

.github/workflows/documentation.yml

@@ -33,10 +33,7 @@ jobs:
         run: "rm composer.json"
 
       - name: "Require phpdocumentor/guides-cli"
-        run: "composer require --dev phpdocumentor/guides-cli dev-main@dev --no-update"
-
-      - name: "Configure minimum stability"
-        run: "composer config minimum-stability dev"
+        run: "composer require --dev phpdocumentor/guides-cli --no-update"
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v2"
@@ -48,4 +45,4 @@ jobs:
           printf '%s\n%s\n\n%s\n' "Dummy title" "===========" "$(cat docs/en/sidebar.rst)" > docs/en/sidebar.rst
 
       - name: "Run guides-cli"
-        run: "vendor/bin/guides -vvv --no-progress docs/en /tmp/test 2>&1 | ( ! grep WARNING )"
+        run: "vendor/bin/guides -vvv --no-progress docs/en 2>&1 | grep -v 'Unknown directive' | ( ! grep WARNING )"

UPGRADE.md

@@ -601,8 +601,48 @@ following classes and methods:
 
 Use `toIterable()` instead.
 
+# Upgrade to 2.17
+
+## Deprecate not-enabling lazy-ghosts
+
+Not enabling lazy ghost objects is deprecated. In ORM 3.0, they will be always enabled.
+Ensure `Doctrine\ORM\Configuration::setLazyGhostObjectEnabled(true)` is called to enable them.
+
 # Upgrade to 2.16
 
+## Deprecated accepting duplicate IDs in the identity map
+
+For any given entity class and ID value, there should be only one object instance
+representing the entity.
+
+In https://github.com/doctrine/orm/pull/10785, a check was added that will guard this
+in the identity map. The most probable cause for violations of this rule are collisions
+of application-provided IDs.
+
+In ORM 2.16.0, the check was added by throwing an exception. In ORM 2.16.1, this will be
+changed to a deprecation notice. ORM 3.0 will make it an exception again. Use
+`\Doctrine\ORM\Configuration::setRejectIdCollisionInIdentityMap()` if you want to opt-in
+to the new mode.
+
+## Potential changes to the order in which `INSERT`s are executed
+
+In https://github.com/doctrine/orm/pull/10547, the commit order computation was improved
+to fix a series of bugs where a correct (working) commit order was previously not found.
+Also, the new computation may get away with fewer queries being executed: By inserting
+referred-to entities first and using their ID values for foreign key fields in subsequent
+`INSERT` statements, additional `UPDATE` statements that were previously necessary can be
+avoided.
+
+When using database-provided, auto-incrementing IDs, this may lead to IDs being assigned
+to entities in a different order than it was previously the case.
+
+## Deprecated `\Doctrine\ORM\Internal\CommitOrderCalculator` and related classes
+
+With changes made to the commit order computation, the internal classes
+`\Doctrine\ORM\Internal\CommitOrderCalculator`, `\Doctrine\ORM\Internal\CommitOrder\Edge`,
+`\Doctrine\ORM\Internal\CommitOrder\Vertex` and `\Doctrine\ORM\Internal\CommitOrder\VertexState`
+have been deprecated and will be removed in ORM 3.0.
+
 ## Deprecated returning post insert IDs from `EntityPersister::executeInserts()`
 
 Persisters implementing `\Doctrine\ORM\Persisters\Entity\EntityPersister` should no longer

composer.json

@@ -38,13 +38,13 @@
     "require-dev": {
         "doctrine/coding-standard": "^12.0",
         "phpbench/phpbench": "^1.0",
-        "phpstan/phpstan": "1.10.18",
+        "phpstan/phpstan": "1.10.35",
         "phpunit/phpunit": "^10.0.14",
         "psr/log": "^1 || ^2 || ^3",
         "squizlabs/php_codesniffer": "3.7.2",
         "symfony/cache": "^5.4 || ^6.2",
         "symfony/var-exporter": "^5.4 || ^6.2",
-        "vimeo/psalm": "5.13.0"
+        "vimeo/psalm": "5.15.0"
     },
     "suggest": {
         "ext-dom": "Provides support for XSD validation for XML mapping files",

docs/en/cookbook/aggregate-fields.rst

@@ -211,7 +211,7 @@ Now look at the following test-code for our entities:
     {
         public function testAddEntry()
         {
-            $account = new Account("123456", $maxCredit = 200);
+            $account = new Account("123456", maxCredit: 200);
             $this->assertEquals(0, $account->getBalance());
     
             $account->addEntry(500);
@@ -223,7 +223,7 @@ Now look at the following test-code for our entities:
     
         public function testExceedMaxLimit()
         {
-            $account = new Account("123456", $maxCredit = 200);
+            $account = new Account("123456", maxCredit: 200);
     
             $this->expectException(Exception::class);
             $account->addEntry(-1000);

docs/en/cookbook/mysql-enums.rst

@@ -43,13 +43,13 @@ entities:
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class Article
     {
         const STATUS_VISIBLE = 'visible';
         const STATUS_INVISIBLE = 'invisible';
 
-        /** @Column(type="string") */
+        #[Column(type: "string")]
         private $status;
 
         public function setStatus($status)
@@ -67,10 +67,10 @@ the **columnDefinition** attribute.
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class Article
     {
-        /** @Column(type="string", columnDefinition="ENUM('visible', 'invisible')") */
+        #[Column(type: "string", columnDefinition: "ENUM('visible', 'invisible')")]
         private $status;
     }
 
@@ -131,10 +131,10 @@ Then in your entity you can just use this type:
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class Article
     {
-        /** @Column(type="enumvisibility") */
+        #[Column(type: "enumvisibility")]
         private $status;
     }
 
@@ -196,4 +196,3 @@ With this base class you can define an enum as easily as:
         protected $name = 'enumvisibility';
         protected $values = array('visible', 'invisible');
     }
-

docs/en/cookbook/validation-of-entities.rst

@@ -58,6 +58,10 @@ First Attributes:
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Mapping\Entity;
+    use Doctrine\ORM\Mapping\HasLifecycleCallbacks;
+    use Doctrine\ORM\Mapping\PrePersist;
+    use Doctrine\ORM\Mapping\PreUpdate;
 
     #[Entity]
     #[HasLifecycleCallbacks]

docs/en/cookbook/working-with-datetime.rst

@@ -162,15 +162,13 @@ requiring timezoned datetimes:
     <?php
     namespace Shipping;
 
-    /**
-     * @Entity
-     */
+     #[Entity]
     class Event
     {
-        /** @Column(type="datetime") */
+        #[Column(type: 'datetime')]
         private $created;
 
-        /** @Column(type="string") */
+        #[Column(type: 'string')]
         private $timezone;
 
         /**

docs/en/index.rst

@@ -18,8 +18,8 @@ Doctrine ORM don't panic. You can get help from different sources:
 -  Report a bug on `GitHub <https://github.com/doctrine/orm/issues>`_.
 -  On `StackOverflow <https://stackoverflow.com/questions/tagged/doctrine-orm>`_
 
-If you need more structure over the different topics you can browse the :doc:`table
-of contents <toc>`.
+If you need more structure over the different topics you can browse the table
+of contents.
 
 Getting Started
 ---------------
@@ -121,5 +121,3 @@ Cookbook
 * **Custom Datatypes**
   :doc:`MySQL Enums <cookbook/mysql-enums>`
   :doc:`Advanced Field Value Conversion <cookbook/advanced-field-value-conversion-using-custom-mapping-types>`
-
-.. include:: toc.rst

docs/en/reference/advanced-configuration.rst

@@ -29,7 +29,7 @@ steps of configuration.
 
     $config = new Configuration;
     $config->setMetadataCache($metadataCache);
-    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
     $config->setMetadataDriverImpl($driverImpl);
     $config->setQueryCache($queryCache);
     $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
@@ -129,7 +129,7 @@ The attribute driver can be injected in the ``Doctrine\ORM\Configuration``:
     <?php
     use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 
-    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
     $config->setMetadataDriverImpl($driverImpl);
 
 The path information to the entities is required for the attribute

docs/en/reference/dql-doctrine-query-language.rst

@@ -1381,7 +1381,7 @@ Result Cache API:
     $query->setResultCacheDriver(new ApcCache());
 
     $query->useResultCache(true)
-          ->setResultCacheLifeTime($seconds = 3600);
+          ->setResultCacheLifeTime(3600);
 
     $result = $query->getResult(); // cache miss
 
@@ -1392,7 +1392,7 @@ Result Cache API:
     $result = $query->getResult(); // saved in given result cache id.
 
     // or call useResultCache() with all parameters:
-    $query->useResultCache(true, $seconds = 3600, 'my_query_result');
+    $query->useResultCache(true, 3600, 'my_query_result');
     $result = $query->getResult(); // cache hit!
 
     // Introspection
@@ -1425,7 +1425,7 @@ userland:
    reloading this data. Partially loaded objects have to be passed to
    ``EntityManager::refresh()`` if they are to be reloaded fully from
    the database. This query hint is deprecated and will be removed
-   in the future (`Details <https://github.com/doctrine/orm/issues/8471>`_)
+   in the future (\ `Details <https://github.com/doctrine/orm/issues/8471>`_)
 -  ``Query::HINT_REFRESH`` - This query is used internally by
    ``EntityManager::refresh()`` and can be used in userland as well.
    If you specify this hint and a query returns the data for an entity
@@ -1457,7 +1457,7 @@ several methods to interact with it:
 
 -  ``Query::setQueryCacheDriver($driver)`` - Allows to set a Cache
    instance
--  ``Query::setQueryCacheLifeTime($seconds = 3600)`` - Set lifetime
+-  ``Query::setQueryCacheLifeTime($seconds)`` - Set lifetime
    of the query caching.
 -  ``Query::expireQueryCache($bool)`` - Enforce the expiring of the
    query cache if set to true.

docs/en/reference/events.rst

@@ -215,6 +215,10 @@ specific to a particular entity class's lifecycle.
         <?php
         use Doctrine\DBAL\Types\Types;
         use Doctrine\ORM\Event\PrePersistEventArgs;
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\HasLifecycleCallbacks;
+        use Doctrine\ORM\Mapping\PrePersist;
+        use Doctrine\ORM\Mapping\PreUpdate;
 
         #[Entity]
         #[HasLifecycleCallbacks]
@@ -408,13 +412,12 @@ prePersist
 
 There are two ways for the ``prePersist`` event to be triggered:
 
-- One is obviously when you call ``EntityManager::persist()``. The
-event is also called for all :ref:`cascaded associations<transitive-persistence>`.
-- The other is inside the
-``flush()`` method when changes to associations are computed and
-this association is marked as :ref:`cascade: persist<transitive-persistence>`. Any new entity found
-during this operation is also persisted and ``prePersist`` called
-on it. This is called :ref:`persistence by reachability<persistence-by-reachability>`.
+- One is when you call ``EntityManager::persist()``. The
+  event is also called for all :ref:`cascaded associations<transitive-persistence>`.
+- The other is inside the ``flush()`` method when changes to associations are computed and
+  this association is marked as :ref:`cascade: persist<transitive-persistence>`. Any new entity found
+  during this operation is also persisted and ``prePersist`` called
+  on it. This is called :ref:`persistence by reachability<persistence-by-reachability>`.
 
 In both cases you get passed a ``PrePersistEventArgs`` instance
 which has access to the entity and the entity manager.
@@ -660,13 +663,21 @@ not directly mapped by Doctrine.
 -  The ``postUpdate`` event occurs after the database
    update operations to entity data. It is not called for a DQL
    ``UPDATE`` statement.
--  The ``postPersist`` event occurs for an entity after
-   the entity has been made persistent. It will be invoked after the
-   database insert operations. Generated primary key values are
-   available in the postPersist event.
+-  The ``postPersist`` event occurs for an entity after the entity has
+   been made persistent. It will be invoked after all database insert
+   operations for new entities have been performed. Generated primary
+   key values will be available for all entities at the time this
+   event is triggered.
 -  The ``postRemove`` event occurs for an entity after the
-   entity has been deleted. It will be invoked after the database
-   delete operations. It is not called for a DQL ``DELETE`` statement.
+   entity has been deleted. It will be invoked after all database
+   delete operations for entity rows have been executed. This event is
+   not called for a DQL ``DELETE`` statement.
+
+.. note::
+
+    At the time ``postPersist`` is called, there may still be collection and/or
+    "extra" updates pending. The database may not yet be completely in
+    sync with the entity states in memory, not even for the new entities.
 
 .. warning::
 
@@ -675,6 +686,19 @@ not directly mapped by Doctrine.
     cascade remove relations. In this case, you should load yourself the proxy in
     the associated ``pre*`` event.
 
+.. warning::
+
+    Making changes to entities and calling ``EntityManager::flush()`` from within
+    ``post*`` event handlers is strongly discouraged, and might be deprecated and
+    eventually prevented in the future.
+
+    The reason is that it causes re-entrance into ``UnitOfWork::commit()`` while a commit
+    is currently being processed. The ``UnitOfWork`` was never designed to support this,
+    and its behavior in this situation is not covered by any tests.
+
+    This may lead to entity or collection updates being missed, applied only in parts and
+    changes being lost at the end of the commit phase.
+
 .. _reference-events-post-load:
 
 postLoad
@@ -848,7 +872,8 @@ Specifying an entity listener instance :
 
     // User.php
 
-    /** @Entity @EntityListeners({"UserListener"}) */
+    #[Entity]
+    #[EntityListeners(["UserListener"])
     class User
     {
         // ....