Merge branch 2.15.x into 2.16.x

* 2.15.x: (23 commits)
  Fix cloning entities when using lazy-ghost proxies
  Fixes recomputation of single entity change set when entity contains enum attributes. Due to the fact that originalEntityData contains enum objects and ReflectionEnumProperty::getValue() returns value of enum, comparison of values are always falsy, resulting to update columns value even though it has not changes.
  Fix code style issues
  Use absolute references
  Avoid colon followed by double colon
  Use correct syntax for references
  Fix invalid reference syntax
  Use rst syntax
  Use internal link
  Escape pipes
  Introduce new workflow to test docs
  Remove lone dash (doctrine#10812)
  Treat id field proprites same as regular field
  Move three "Ticket/"-style tests to the right namespace
  Follow recommendation about multiline type
  Fix unserialize() errors when running tests on PHP 8.3 (doctrine#10803)
  Explain `EntityManager::getReference()` peculiarities (doctrine#10800)
  Upgrade to Psalm 5.13
  test: assert `postLoad` has data first
  distinct() updates QueryBuilder state correctly
  ...

.github/workflows/documentation.yml

@@ -0,0 +1,47 @@
+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: "Run guides-cli"
+        run: "vendor/bin/guides -vvv --no-progress docs/en /tmp/test 2>&1 | ( ! grep WARNING )"

composer.json

@@ -49,7 +49,7 @@
         "symfony/cache": "^4.4 || ^5.4 || ^6.0",
         "symfony/var-exporter": "^4.4 || ^5.4 || ^6.2",
         "symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0",
-        "vimeo/psalm": "4.30.0 || 5.12.0"
+        "vimeo/psalm": "4.30.0 || 5.13.0"
     },
     "conflict": {
         "doctrine/annotations": "<1.13 || >= 3.0"

docs/en/index.rst

@@ -34,32 +34,32 @@ 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:`Docblock Annotations <reference/annotations-reference>` |
-  :doc:`Attributes <reference/attributes-reference>` |
-  :doc:`XML <reference/xml-mapping>` |
-  :doc:`YAML <reference/yaml-mapping>` |
+  :doc:`Docblock Annotations <reference/annotations-reference>` \|
+  :doc:`Attributes <reference/attributes-reference>` \|
+  :doc:`XML <reference/xml-mapping>` \|
+  :doc:`YAML <reference/yaml-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
@@ -102,20 +102,20 @@ 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:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` |
-  :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:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` \|
+  :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**

docs/en/reference/advanced-configuration.rst

@@ -311,10 +311,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
 
@@ -324,15 +326,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
 ~~~~~~~~~~~~~~~~~~~
 

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
 ~~~~~~~~~~~~~~~~~

docs/en/reference/basic-mapping.rst

@@ -460,7 +460,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
 ^^^^^^^^^^^^^^^^^^

docs/en/reference/configuration.rst

@@ -104,7 +104,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::
 

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
 ~~~~~~~~~

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
 ------------------------

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:
 
@@ -380,7 +380,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

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>`.

docs/en/reference/limitations-and-known-issues.rst

@@ -145,7 +145,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
@@ -162,7 +162,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"

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

docs/en/tutorials/getting-started.rst

@@ -102,8 +102,7 @@ Install Doctrine using the Composer Dependency Management tool, by calling:
 This will install the packages Doctrine Common, Doctrine DBAL, Doctrine ORM,
 into the ``vendor`` directory.
 
-Add the following directories:
-::
+Add the following directories::
 
     doctrine2-tutorial
     |-- config

lib/Doctrine/ORM/Mapping/Driver/AttributeDriver.php

@@ -23,7 +23,6 @@
 use function constant;
 use function defined;
 use function get_class;
-use function sprintf;
 
 use const PHP_VERSION_ID;
 
@@ -57,10 +56,10 @@ class AttributeDriver extends CompatibilityAnnotationDriver
     public function __construct(array $paths, bool $reportFieldsWhereDeclared = false)
     {
         if (PHP_VERSION_ID < 80000) {
-            throw new LogicException(sprintf(
+            throw new LogicException(
                 'The attribute metadata driver cannot be enabled on PHP 7. Please upgrade to PHP 8 or choose a different'
                 . ' metadata driver.'
-            ));
+            );
         }
 
         $this->reader = new AttributeReader();