Merge pull request #10888 from greg0ire/partial-merge-up

Partial merge up of 2.17.x into 3.0.x
doctrine · Aug 8, 2023 · 394f6fe · 394f6fe
2 parents 2dc19e6 + 7d9a2c0
commit 394f6fe
Show file tree

Hide file tree

Showing 61 changed files with 1,396 additions and 356 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,51 @@
+name: "Documentation"
+
+on:
+  pull_request:
+    branches:
+      - "*.x"
+    paths:
+      - .github/workflows/documentation.yml
+      - docs/**
+  push:
+    branches:
+      - "*.x"
+    paths:
+      - .github/workflows/documentation.yml
+      - docs/**
+
+jobs:
+  validate-with-guides:
+    name: "Validate documentation with phpDocumentor/guides"
+    runs-on: "ubuntu-22.04"
+
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v3"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.2"
+
+      - name: "Remove existing composer file"
+        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"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v2"
+        with:
+          dependency-versions: "highest"
+
+      - name: "Add dummy title to the sidebar"
+        run: |
+          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 )"
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -603,6 +603,12 @@ Use `toIterable()` instead.
 
 # Upgrade to 2.16
 
+## Deprecated returning post insert IDs from `EntityPersister::executeInserts()`
+
+Persisters implementing `\Doctrine\ORM\Persisters\Entity\EntityPersister` should no longer
+return an array of post insert IDs from their `::executeInserts()` method. Make the
+persister call `Doctrine\ORM\UnitOfWork::assignPostInsertId()` instead.
+
 ## Changing the way how reflection-based mapping drivers report fields, deprecated the "old" mode
 
 In ORM 3.0, a change will be made regarding how the `AttributeDriver` reports field mappings.

diff --git a/composer.json b/composer.json
@@ -44,7 +44,7 @@
         "squizlabs/php_codesniffer": "3.7.2",
         "symfony/cache": "^5.4 || ^6.2",
         "symfony/var-exporter": "^5.4 || ^6.2",
-        "vimeo/psalm": "5.12.0"
+        "vimeo/psalm": "5.13.0"
     },
     "suggest": {
         "ext-dom": "Provides support for XSD validation for XML mapping files",

diff --git a/docs/en/index.rst b/docs/en/index.rst
@@ -34,30 +34,30 @@ Mapping Objects onto a Database
 -------------------------------
 
 * **Mapping**:
-  :doc:`Objects <reference/basic-mapping>` |
-  :doc:`Associations <reference/association-mapping>` |
+  :doc:`Objects <reference/basic-mapping>` \|
+  :doc:`Associations <reference/association-mapping>` \|
   :doc:`Inheritance <reference/inheritance-mapping>`
 
 * **Drivers**:
-  :doc:`Attributes <reference/attributes-reference>` |
-  :doc:`XML <reference/xml-mapping>` |
+  :doc:`Attributes <reference/attributes-reference>` \|
+  :doc:`XML <reference/xml-mapping>` \|
   :doc:`PHP <reference/php-mapping>`
 
 Working with Objects
 --------------------
 
 * **Basic Reference**:
-  :doc:`Entities <reference/working-with-objects>` |
-  :doc:`Associations <reference/working-with-associations>` |
+  :doc:`Entities <reference/working-with-objects>` \|
+  :doc:`Associations <reference/working-with-associations>` \|
   :doc:`Events <reference/events>`
 
 * **Query Reference**:
-  :doc:`DQL <reference/dql-doctrine-query-language>` |
-  :doc:`QueryBuilder <reference/query-builder>` |
+  :doc:`DQL <reference/dql-doctrine-query-language>` \|
+  :doc:`QueryBuilder <reference/query-builder>` \|
   :doc:`Native SQL <reference/native-sql>`
 
 * **Internals**:
-  :doc:`Internals explained <reference/unitofwork>` |
+  :doc:`Internals explained <reference/unitofwork>` \|
   :doc:`Associations <reference/unitofwork-associations>`
 
 Advanced Topics
@@ -100,19 +100,19 @@ Cookbook
 --------
 
 * **Patterns**:
-  :doc:`Aggregate Fields <cookbook/aggregate-fields>` |
-  :doc:`Decorator Pattern <cookbook/decorator-pattern>` |
+  :doc:`Aggregate Fields <cookbook/aggregate-fields>` \|
+  :doc:`Decorator Pattern <cookbook/decorator-pattern>` \|
   :doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>`
 
 * **DQL Extension Points**:
-  :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` |
+  :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` \|
   :doc:`DQL User-Defined-Functions <cookbook/dql-user-defined-functions>`
 
 * **Implementation**:
-  :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` |
-  :doc:`Working with DateTime <cookbook/working-with-datetime>` |
-  :doc:`Validation <cookbook/validation-of-entities>` |
-  :doc:`Entities in the Session <cookbook/entities-in-session>` |
+  :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` \|
+  :doc:`Working with DateTime <cookbook/working-with-datetime>` \|
+  :doc:`Validation <cookbook/validation-of-entities>` \|
+  :doc:`Entities in the Session <cookbook/entities-in-session>` \|
   :doc:`Keeping your Modules independent <cookbook/resolve-target-entity-listener>`
 
 * **Hidden Gems**

diff --git a/docs/en/reference/advanced-configuration.rst b/docs/en/reference/advanced-configuration.rst
@@ -306,10 +306,12 @@ Reference Proxies
 
 The method ``EntityManager#getReference($entityName, $identifier)``
 lets you obtain a reference to an entity for which the identifier
-is known, without loading that entity from the database. This is
-useful, for example, as a performance enhancement, when you want to
-establish an association to an entity for which you have the
-identifier. You could simply do this:
+is known, without necessarily loading that entity from the database.
+This is useful, for example, as a performance enhancement, when you
+want to establish an association to an entity for which you have the
+identifier.
+
+Consider the following example:
 
 .. code-block:: php
 
@@ -319,15 +321,33 @@ identifier. You could simply do this:
     $item = $em->getReference('MyProject\Model\Item', $itemId);
     $cart->addItem($item);
 
-Here, we added an Item to a Cart without loading the Item from the
-database. If you access any state that isn't yet available in the
-Item instance, the proxying mechanism would fully initialize the
-object's state transparently from the database. Here
-$item is actually an instance of the proxy class that was generated
-for the Item class but your code does not need to care. In fact it
-**should not care**. Proxy objects should be transparent to your
+Whether the object being returned from ``EntityManager#getReference()``
+is a proxy or a direct instance of the entity class may depend on different
+factors, including whether the entity has already been loaded into memory
+or entity inheritance being used. But your code does not need to care
+and in fact it **should not care**. Proxy objects should be transparent to your
 code.
 
+When using the ``EntityManager#getReference()`` method, you need to be aware
+of a few peculiarities.
+
+At the best case, the ORM can avoid querying the database at all. But, that
+also means that this method will not throw an exception when an invalid value
+for the ``$identifier`` parameter is passed. ``$identifier`` values are
+not checked and there is no guarantee that the requested entity instance even
+exists – the method will still return a proxy object.
+
+Its only when the proxy has to be fully initialized or associations cannot
+be written to the database that invalid ``$identifier`` values may lead to
+exceptions.
+
+The ``EntityManager#getReference()`` is mostly useful when you only
+need a reference to some entity to make an association, like in the example
+above. In that case, it can save you from loading data from the database
+that you don't need. But remember – as soon as you read any property values
+besides those making up the ID, a database request will be made to initialize
+all fields.
+
 Association proxies
 ~~~~~~~~~~~~~~~~~~~
 

diff --git a/docs/en/reference/architecture.rst b/docs/en/reference/architecture.rst
@@ -102,7 +102,7 @@ persistent entity state and mapping information for its subclasses,
 but which is not itself an entity.
 
 Mapped superclasses are explained in greater detail in the chapter
-on :doc:`inheritance mapping <reference/inheritance-mapping>`.
+on :doc:`inheritance mapping </reference/inheritance-mapping>`.
 
 Transient Classes
 ~~~~~~~~~~~~~~~~~

diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst
@@ -359,7 +359,7 @@ Here is the list of possible generation strategies:
    a new entity is passed to ``EntityManager#persist``. NONE is the
    same as leaving off the ``#[GeneratedValue]`` entirely.
 -  ``CUSTOM``: With this option, you can use the ``#[CustomIdGenerator]`` attribute.
-   It will allow you to pass a :doc:`class of your own to generate the identifiers.<_annref_customidgenerator>`
+   It will allow you to pass a :ref:`class of your own to generate the identifiers.<annref_customidgenerator>`
 
 Sequence Generator
 ^^^^^^^^^^^^^^^^^^

diff --git a/docs/en/reference/configuration.rst b/docs/en/reference/configuration.rst
@@ -82,7 +82,7 @@ Inside the ``ORMSetup`` methods several assumptions are made:
     In order to have ``ORMSetup`` configure the cache automatically, the library ``symfony/cache``
     has to be installed as a dependency.
 
-If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration <reference/advanced-configuration>` section.
+If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration </reference/advanced-configuration>` section.
 
 .. note::
 

diff --git a/docs/en/reference/dql-doctrine-query-language.rst b/docs/en/reference/dql-doctrine-query-language.rst
@@ -1336,8 +1336,8 @@ There are situations when a query you want to execute returns a
 very large result-set that needs to be processed. All the
 previously described hydration modes completely load a result-set
 into memory which might not be feasible with large result sets. See
-the `Batch Processing <batch-processing.html>`_ section on details how
-to iterate large result sets.
+the :doc:`Batch Processing </reference/batch-processing>` section on
+details how to iterate large result sets.
 
 Functions
 ~~~~~~~~~

diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst
@@ -247,10 +247,10 @@ specific to a particular entity class's lifecycle.
 
         <?xml version="1.0" encoding="UTF-8"?>
 
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
             <entity name="User">
                 <!-- ... -->
                 <lifecycle-callbacks>

diff --git a/docs/en/reference/improving-performance.rst b/docs/en/reference/improving-performance.rst
@@ -91,7 +91,7 @@ Apply Best Practices
 A lot of the points mentioned in the Best Practices chapter will
 also positively affect the performance of Doctrine.
 
-See :doc:`Best Practices <reference/best-practices>`
+See :doc:`Best Practices </reference/best-practices>`
 
 Change Tracking policies
 ------------------------

diff --git a/docs/en/reference/inheritance-mapping.rst b/docs/en/reference/inheritance-mapping.rst
@@ -35,7 +35,7 @@ have to be used.
     superclass, since they require the "many" side to hold the foreign
     key.
 
-    It is, however, possible to use the :doc:`ResolveTargetEntityListener <cookbook/resolve-target-entity-listener>`
+    It is, however, possible to use the :doc:`ResolveTargetEntityListener </cookbook/resolve-target-entity-listener>`
     to replace references to a mapped superclass with an entity class at runtime.
     As long as there is only one entity subclass inheriting from the mapped
     superclass and all references to the mapped superclass are resolved to that
@@ -45,7 +45,7 @@ have to be used.
 .. warning::
 
     At least when using attributes or annotations to specify your mapping,
-    it _seems_ as if you could inherit from a base class that is neither
+    it *seems* as if you could inherit from a base class that is neither
     an entity nor a mapped superclass, but has properties with mapping configuration
     on them that would also be used in the inheriting class.
 
@@ -60,7 +60,7 @@ have to be used.
     You may be tempted to use traits to mix mapped fields or relationships
     into your entity classes to circumvent some of the limitations of
     mapped superclasses. Before doing that, please read the section on traits
-    in the :doc:`Limitations and Known Issues <reference/limitations-and-known-issues>` chapter.
+    in the :doc:`Limitations and Known Issues </reference/limitations-and-known-issues>` chapter.
 
 Example:
 
@@ -342,7 +342,7 @@ It is not supported to use overrides in entity inheritance scenarios.
 .. note::
 
     When using traits, make sure not to miss the warnings given in the
-    :doc:`Limitations and Known Issues<reference/limitations-and-known-issues>` chapter.
+    :doc:`Limitations and Known Issues</reference/limitations-and-known-issues>` chapter.
 
 
 Association Override

diff --git a/docs/en/reference/installation.rst b/docs/en/reference/installation.rst
@@ -1,4 +1,4 @@
 Installation
 ============
 
-The installation chapter has moved to :doc:`Installation and Configuration <reference/configuration>`_.
+The installation chapter has moved to :doc:`Installation and Configuration </reference/configuration>`.
diff --git a/docs/en/reference/limitations-and-known-issues.rst b/docs/en/reference/limitations-and-known-issues.rst
@@ -136,7 +136,7 @@ more than two years after the initial Doctrine 2 release and the time where
 core components were designed.
 
 In fact, this documentation mentions traits only in the context of
-:doc:`overriding field association mappings in subclasses <tutorials/override-field-association-mappings-in-subclasses>`.
+:doc:`overriding field association mappings in subclasses </tutorials/override-field-association-mappings-in-subclasses>`.
 Coverage of traits in test cases is practically nonexistent.
 
 Thus, you should at least be aware that when using traits in your entity and
@@ -153,7 +153,7 @@ that, some precedence and conflict resolution rules apply.
 
 When it comes to loading mapping configuration, the annotation and attribute drivers
 rely on PHP reflection to inspect class properties including their docblocks.
-As long as the results are consistent with what a solution _without_ traits would
+As long as the results are consistent with what a solution *without* traits would
 have produced, this is probably fine.
 
 However, to mention known limitations, it is currently not possible to use "class"

diff --git a/docs/en/reference/query-builder.rst b/docs/en/reference/query-builder.rst
@@ -578,8 +578,6 @@ of DQL. It takes 3 parameters: ``$dqlPartName``, ``$dqlPart`` and
    not (no effect on the ``where`` and ``having`` DQL query parts,
    which always override all previously defined items)
 
--
-
 .. code-block:: php
 
     <?php

diff --git a/docs/en/reference/second-level-cache.rst b/docs/en/reference/second-level-cache.rst
@@ -298,7 +298,10 @@ level cache region.
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="Country">
             <cache usage="READ_ONLY" region="my_entity_region" />
             <id name="id" type="integer" column="id">
@@ -347,7 +350,10 @@ It caches the primary keys of association and cache each element will be cached
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="State">
 
             <cache usage="NONSTRICT_READ_WRITE" />

diff --git a/docs/en/reference/xml-mapping.rst b/docs/en/reference/xml-mapping.rst
@@ -17,9 +17,9 @@ setup for the latest code in trunk.
 
 .. code-block:: xml
 
-    <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
           xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
         ...
@@ -103,9 +103,9 @@ of several common elements:
 
     // Doctrine.Tests.ORM.Mapping.User.dcm.xml
     <?xml version="1.0" encoding="UTF-8"?>
-    <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
           xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
         <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
@@ -769,9 +769,9 @@ entity relationship. You can define this in XML with the "association-key" attri
 
 .. code-block:: xml
 
-    <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
           xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
          <entity name="Application\Model\ArticleAttribute">