Merge branch '2.19.x' into 3.1.x

* 2.19.x:
  Fix BIGINT validation (#11414)
  Fix templated phpdoc return type (#11407)
  [Documentation] Merging "Query Result Formats" with "Hydration Modes"
  Fix psalm errors: remove override of template type
  Update dql-doctrine-query-language.rst
  Adding `NonUniqueResultException`
  [Documentation] Query Result Formats

docs/en/reference/architecture.rst

@@ -18,7 +18,7 @@ well.
 Requirements
 ------------
 
-Doctrine ORM requires a minimum of PHP 7.1. For greatly improved
+Doctrine ORM requires a minimum of PHP 8.1. For greatly improved
 performance it is also recommended that you use APC with PHP.
 
 Doctrine ORM Packages

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

@@ -976,7 +976,7 @@ The Query class
 ---------------
 
 An instance of the ``Doctrine\ORM\Query`` class represents a DQL
-query. You create a Query instance be calling
+query. You create a Query instance by calling
 ``EntityManager#createQuery($dql)``, passing the DQL query string.
 Alternatively you can create an empty ``Query`` instance and invoke
 ``Query#setDQL($dql)`` afterwards. Here are some examples:
@@ -993,58 +993,146 @@ Alternatively you can create an empty ``Query`` instance and invoke
     $q = $em->createQuery();
     $q->setDQL('select u from MyProject\Model\User u');
 
-Query Result Formats
-~~~~~~~~~~~~~~~~~~~~
+Query Result Formats (Hydration Modes)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The format in which the result of a DQL SELECT query is returned
-can be influenced by a so-called ``hydration mode``. A hydration
-mode specifies a particular way in which a SQL result set is
-transformed. Each hydration mode has its own dedicated method on
-the Query class. Here they are:
+The way in which the SQL result set of a DQL SELECT query is transformed
+to PHP is determined by the so-called "hydration mode".
 
+``getResult()``
+^^^^^^^^^^^^^^^
 
--  ``Query#getResult()``: Retrieves a collection of objects. The
-   result is either a plain collection of objects (pure) or an array
-   where the objects are nested in the result rows (mixed).
--  ``Query#getSingleResult()``: Retrieves a single object. If the
-   result contains more than one object, an ``NonUniqueResultException``
-   is thrown. If the result contains no objects, an ``NoResultException``
-   is thrown. The pure/mixed distinction does not apply.
--  ``Query#getOneOrNullResult()``: Retrieve a single object. If the
-   result contains more than one object, a ``NonUniqueResultException``
-   is thrown. If no object is found null will be returned.
--  ``Query#getArrayResult()``: Retrieves an array graph (a nested
-   array) that is largely interchangeable with the object graph
-   generated by ``Query#getResult()`` for read-only purposes.
+Retrieves a collection of objects. The result is either a plain collection of objects (pure) or an array
+where the objects are nested in the result rows (mixed):
 
-    .. note::
+.. code-block:: php
 
-        An array graph can differ from the corresponding object
-        graph in certain scenarios due to the difference of the identity
-        semantics between arrays and objects.
+    <?php
+    use Doctrine\ORM\AbstractQuery;
 
+    $query = $em->createQuery('SELECT u FROM User u');
+    $users = $query->getResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_OBJECT);
 
+- Objects fetched in a FROM clause are returned as a Set, that means every
+  object is only ever included in the resulting array once. This is the case
+  even when using JOIN or GROUP BY in ways that return the same row for an
+  object multiple times. If the hydrator sees the same object multiple times,
+  then it makes sure it is only returned once.
 
--  ``Query#getScalarResult()``: Retrieves a flat/rectangular result
-   set of scalar values that can contain duplicate data. The
-   pure/mixed distinction does not apply.
--  ``Query#getSingleScalarResult()``: Retrieves a single scalar
-   value from the result returned by the dbms. If the result contains
-   more than a single scalar value, an exception is thrown. The
-   pure/mixed distinction does not apply.
+- If an object is already in memory from a previous query of any kind, then
+  then the previous object is used, even if the database may contain more
+  recent data. This even happens if the previous object is still an unloaded proxy.
 
-Instead of using these methods, you can alternatively use the
-general-purpose method
-``Query#execute(array $params = [], $hydrationMode = Query::HYDRATE_OBJECT)``.
-Using this method you can directly supply the hydration mode as the
-second parameter via one of the Query constants. In fact, the
-methods mentioned earlier are just convenient shortcuts for the
-execute method. For example, the method ``Query#getResult()``
-internally invokes execute, passing in ``Query::HYDRATE_OBJECT`` as
-the hydration mode.
+``getArrayResult()``
+^^^^^^^^^^^^^^^^^^^^
 
-The use of the methods mentioned earlier is generally preferred as
-it leads to more concise code.
+Retrieves an array graph (a nested array) for read-only purposes.
+
+.. note::
+
+    An array graph can differ from the corresponding object
+    graph in certain scenarios due to the difference of the identity
+    semantics between arrays and objects.
+
+.. code-block:: php
+
+    <?php
+    $users = $query->getArrayResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_ARRAY);
+
+``getScalarResult()``
+^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a flat/rectangular result set of scalar values that can contain duplicate data. The
+pure/mixed distinction does not apply.
+
+.. code-block:: php
+
+    <?php
+    $users = $query->getScalarResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_SCALAR);
+
+Fields from classes are prefixed by the DQL alias in the result.
+A query of the kind `SELECT u.name ...` returns a key `u_name` in the result rows.
+
+``getSingleScalarResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single scalar value from the result returned by the database. If the result contains
+more than a single scalar value, a ``NonUniqueResultException`` is thrown. The pure/mixed distinction does not apply.
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT COUNT(u.id) FROM User u');
+    $numUsers = $query->getSingleScalarResult();
+    // same as:
+    $numUsers = $query->getResult(AbstractQuery::HYDRATE_SINGLE_SCALAR);
+
+``getSingleColumnResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves an array from a one-dimensional array of scalar values:
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT a.id FROM User u');
+    $ids = $query->getSingleColumnResult();
+    // same as:
+    $ids = $query->getResult(AbstractQuery::HYDRATE_SCALAR_COLUMN);
+
+``getSingleResult()``
+^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single object. If the result contains more than one object, a ``NonUniqueResultException``
+is thrown. If the result contains no objects, a ``NoResultException`` is thrown. The pure/mixed distinction does not apply.
+
+``getOneOrNullResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single object. If the result contains more than one object, a ``NonUniqueResultException``
+is thrown. If no object is found, ``null`` will be returned.
+
+Custom Hydration Modes
+^^^^^^^^^^^^^^^^^^^^^^
+
+You can easily add your own custom hydration modes by first
+creating a class which extends ``AbstractHydrator``:
+
+.. code-block:: php
+
+    <?php
+    namespace MyProject\Hydrators;
+
+    use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
+
+    class CustomHydrator extends AbstractHydrator
+    {
+        protected function _hydrateAll()
+        {
+            return $this->_stmt->fetchAllAssociative();
+        }
+    }
+
+Next you just need to add the class to the ORM configuration:
+
+.. code-block:: php
+
+    <?php
+    $em->getConfiguration()->addCustomHydrationMode('CustomHydrator', 'MyProject\Hydrators\CustomHydrator');
+
+Now the hydrator is ready to be used in your queries:
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT u FROM CmsUser u');
+    $results = $query->getResult('CustomHydrator');
 
 Pure and Mixed Results
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -1148,165 +1236,6 @@ will return the rows iterating the different top-level entities.
         [2] => Object (User)
         [3] => Object (Group)
 
-
-Hydration Modes
-~~~~~~~~~~~~~~~
-
-Each of the Hydration Modes makes assumptions about how the result
-is returned to user land. You should know about all the details to
-make best use of the different result formats:
-
-The constants for the different hydration modes are:
-
-
--  ``Query::HYDRATE_OBJECT``
--  ``Query::HYDRATE_ARRAY``
--  ``Query::HYDRATE_SCALAR``
--  ``Query::HYDRATE_SINGLE_SCALAR``
--  ``Query::HYDRATE_SCALAR_COLUMN``
-
-Object Hydration
-^^^^^^^^^^^^^^^^
-
-Object hydration hydrates the result set into the object graph:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_OBJECT);
-
-Sometimes the behavior in the object hydrator can be confusing, which is
-why we are listing as many of the assumptions here for reference:
-
-- Objects fetched in a FROM clause are returned as a Set, that means every
-  object is only ever included in the resulting array once. This is the case
-  even when using JOIN or GROUP BY in ways that return the same row for an
-  object multiple times. If the hydrator sees the same object multiple times,
-  then it makes sure it is only returned once.
-
-- If an object is already in memory from a previous query of any kind, then
-  then the previous object is used, even if the database may contain more
-  recent data. Data from the database is discarded. This even happens if the
-  previous object is still an unloaded proxy.
-
-This list might be incomplete.
-
-Array Hydration
-^^^^^^^^^^^^^^^
-
-You can run the same query with array hydration and the result set
-is hydrated into an array that represents the object graph:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_ARRAY);
-
-You can use the ``getArrayResult()`` shortcut as well:
-
-.. code-block:: php
-
-    <?php
-    $users = $query->getArrayResult();
-
-Scalar Hydration
-^^^^^^^^^^^^^^^^
-
-If you want to return a flat rectangular result set instead of an
-object graph you can use scalar hydration:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_SCALAR);
-    echo $users[0]['u_id'];
-
-The following assumptions are made about selected fields using
-Scalar Hydration:
-
-
-1. Fields from classes are prefixed by the DQL alias in the result.
-   A query of the kind 'SELECT u.name ..' returns a key 'u_name' in
-   the result rows.
-
-Single Scalar Hydration
-^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have a query which returns just a single scalar value you can use
-single scalar hydration:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT COUNT(a.id) FROM CmsUser u LEFT JOIN u.articles a WHERE u.username = ?1 GROUP BY u.id');
-    $query->setParameter(1, 'jwage');
-    $numArticles = $query->getResult(Query::HYDRATE_SINGLE_SCALAR);
-
-You can use the ``getSingleScalarResult()`` shortcut as well:
-
-.. code-block:: php
-
-    <?php
-    $numArticles = $query->getSingleScalarResult();
-
-Scalar Column Hydration
-^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have a query which returns a one-dimensional array of scalar values
-you can use scalar column hydration:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT a.id FROM CmsUser u');
-    $ids = $query->getResult(Query::HYDRATE_SCALAR_COLUMN);
-
-You can use the ``getSingleColumnResult()`` shortcut as well:
-
-.. code-block:: php
-
-    <?php
-    $ids = $query->getSingleColumnResult();
-
-Custom Hydration Modes
-^^^^^^^^^^^^^^^^^^^^^^
-
-You can easily add your own custom hydration modes by first
-creating a class which extends ``AbstractHydrator``:
-
-.. code-block:: php
-
-    <?php
-    namespace MyProject\Hydrators;
-
-    use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
-
-    class CustomHydrator extends AbstractHydrator
-    {
-        protected function _hydrateAll()
-        {
-            return $this->_stmt->fetchAllAssociative();
-        }
-    }
-
-Next you just need to add the class to the ORM configuration:
-
-.. code-block:: php
-
-    <?php
-    $em->getConfiguration()->addCustomHydrationMode('CustomHydrator', 'MyProject\Hydrators\CustomHydrator');
-
-Now the hydrator is ready to be used in your queries:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $results = $query->getResult('CustomHydrator');
-
 Iterating Large Result Sets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/en/tutorials/getting-started.rst

@@ -27,7 +27,7 @@ What is Doctrine?
 -----------------
 
 Doctrine ORM is an `object-relational mapper (ORM) <https://en.wikipedia.org/wiki/Object-relational_mapping>`_
-for PHP 7.1+ that provides transparent persistence for PHP objects. It uses the Data Mapper
+for PHP that provides transparent persistence for PHP objects. It uses the Data Mapper
 pattern at the heart, aiming for a complete separation of your domain/business
 logic from the persistence in a relational database management system.
 

phpstan-baseline.neon

@@ -115,11 +115,6 @@ parameters:
 			count: 1
 			path: src/EntityManagerInterface.php
 
-		-
-			message: "#^Template type T of method Doctrine\\\\ORM\\\\EntityManagerInterface\\:\\:getClassMetadata\\(\\) is not referenced in a parameter\\.$#"
-			count: 1
-			path: src/EntityManagerInterface.php
-
 		-
 			message: "#^Method Doctrine\\\\ORM\\\\EntityRepository\\:\\:matching\\(\\) should return Doctrine\\\\Common\\\\Collections\\\\AbstractLazyCollection\\<int, T of object\\>&Doctrine\\\\Common\\\\Collections\\\\Selectable\\<int, T of object\\> but returns Doctrine\\\\ORM\\\\LazyCriteriaCollection\\<\\(int\\|string\\), object\\>\\.$#"
 			count: 1

phpstan-dbal3.neon

@@ -20,10 +20,6 @@ parameters:
             message: '~^Method Doctrine\\ORM\\Persisters\\Entity\\BasicEntityPersister\:\:getArrayBindingType\(\) never returns .* so it can be removed from the return type\.$~'
             path: src/Persisters/Entity/BasicEntityPersister.php
 
-        -
-            message: '~^Unreachable statement \- code above always terminates\.$~'
-            path: src/Mapping/AssociationMapping.php
-
         - '~^Class Doctrine\\DBAL\\Platforms\\SQLitePlatform not found\.$~'
 
         # To be removed in 4.0

phpstan.neon

@@ -20,10 +20,6 @@ parameters:
             message: '~^Method Doctrine\\ORM\\Persisters\\Entity\\BasicEntityPersister\:\:getArrayBindingType\(\) never returns .* so it can be removed from the return type\.$~'
             path: src/Persisters/Entity/BasicEntityPersister.php
 
-        -
-            message: '~^Unreachable statement \- code above always terminates\.$~'
-            path: src/Mapping/AssociationMapping.php
-
         # Compatibility with DBAL 3
         # See https://github.com/doctrine/dbal/pull/3480
         -

psalm-baseline.xml

@@ -154,14 +154,6 @@
       <code><![CDATA[$className]]></code>
     </ArgumentTypeCoercion>
   </file>
-  <file src="src/Decorator/EntityManagerDecorator.php">
-    <InvalidReturnStatement>
-      <code><![CDATA[$this->wrapped->getClassMetadata($className)]]></code>
-    </InvalidReturnStatement>
-    <InvalidReturnType>
-      <code><![CDATA[ClassMetadata]]></code>
-    </InvalidReturnType>
-  </file>
   <file src="src/EntityManager.php">
     <ArgumentTypeCoercion>
       <code><![CDATA[$className]]></code>
@@ -174,11 +166,9 @@
       <code><![CDATA[$persister->load($sortedId, null, null, [], $lockMode)]]></code>
       <code><![CDATA[$persister->loadById($sortedId)]]></code>
       <code><![CDATA[$this->metadataFactory]]></code>
-      <code><![CDATA[$this->metadataFactory->getMetadataFor($className)]]></code>
     </InvalidReturnStatement>
     <InvalidReturnType>
       <code><![CDATA[ClassMetadataFactory]]></code>
-      <code><![CDATA[Mapping\ClassMetadata]]></code>
     </InvalidReturnType>
     <PossiblyNullArgument>
       <code><![CDATA[$config->getProxyDir()]]></code>
@@ -251,9 +241,6 @@
     </UnsupportedReferenceUsage>
   </file>
   <file src="src/Internal/Hydration/ObjectHydrator.php">
-    <InvalidArgument>
-      <code><![CDATA[$element]]></code>
-    </InvalidArgument>
     <PossiblyFalseArgument>
       <code><![CDATA[$index]]></code>
     </PossiblyFalseArgument>
@@ -298,6 +285,10 @@
       <code><![CDATA[$this->columnNames]]></code>
     </DeprecatedProperty>
     <InvalidArgument>
+      <code><![CDATA[$mapping]]></code>
+      <code><![CDATA[$mapping]]></code>
+      <code><![CDATA[$mapping]]></code>
+      <code><![CDATA[$mapping]]></code>
       <code><![CDATA[$mapping]]></code>
       <code><![CDATA[$mapping]]></code>
       <code><![CDATA[$mapping]]></code>

src/EntityManagerInterface.php

@@ -234,7 +234,7 @@ interface EntityManagerInterface extends ObjectManager
      *
      * @psalm-param string|class-string<T> $className
      *
-     * @psalm-return Mapping\ClassMetadata<T>
+     * @psalm-return ($className is class-string<T> ? Mapping\ClassMetadata<T> : Mapping\ClassMetadata<object>)
      *
      * @psalm-template T of object
      */

src/LazyCriteriaCollection.php

@@ -64,11 +64,11 @@ class LazyCriteriaCollection extends AbstractLazyCollection implements Selectabl
     }
 
     /**
-     * {@inheritDoc}
-     *
      * Do an optimized search of an element
      *
-     * @template TMaybeContained
+     * @param mixed $element The element to search for.
+     *
+     * @return bool TRUE if the collection contains $element, FALSE otherwise.
      */
     public function contains(mixed $element): bool
     {

src/Mapping/AssociationMapping.php

@@ -27,7 +27,7 @@ abstract class AssociationMapping implements ArrayAccess
     /**
      * The fetching strategy to use for the association, usually defaults to FETCH_LAZY.
      *
-     * @var ClassMetadata::FETCH_*
+     * @var ClassMetadata::FETCH_*|null
      */
     public int|null $fetch = null;
 
@@ -96,13 +96,26 @@ abstract class AssociationMapping implements ArrayAccess
     }
 
     /**
+     * @param mixed[] $mappingArray
      * @psalm-param array{
      *     fieldName: string,
      *     sourceEntity: class-string,
      *     targetEntity: class-string,
+     *     cascade?: list<'persist'|'remove'|'detach'|'refresh'|'all'>,
+     *     fetch?: ClassMetadata::FETCH_*|null,
+     *     inherited?: class-string|null,
+     *     declared?: class-string|null,
+     *     cache?: array<mixed>|null,
+     *     id?: bool|null,
+     *     isOnDeleteCascade?: bool|null,
+     *     originalClass?: class-string|null,
+     *     originalField?: string|null,
+     *     orphanRemoval?: bool,
+     *     unique?: bool|null,
      *     joinTable?: mixed[]|null,
      *     type?: int,
-     *     isOwningSide: bool, ...} $mappingArray
+     *     isOwningSide: bool,
+     * } $mappingArray
      */
     public static function fromMappingArray(array $mappingArray): static
     {

src/Mapping/ClassMetadata.php

@@ -1152,7 +1152,7 @@ class ClassMetadata implements PersistenceClassMetadata, Stringable
      *     fieldName?: string,
      *     columnName?: string,
      *     id?: bool,
-     *     generated?: int,
+     *     generated?: self::GENERATED_*,
      *     enumType?: class-string,
      * } $mapping The field mapping to validate & complete.
      *

src/Mapping/EmbeddedClassMapping.php

@@ -49,10 +49,12 @@ final class EmbeddedClassMapping implements ArrayAccess
 
     /**
      * @psalm-param array{
-     *    class: class-string,
-     *    columnPrefix?: false|string|null,
-     *    declaredField?: string|null,
-     *    originalField?: string|null
+     *     class: class-string,
+     *     columnPrefix?: false|string|null,
+     *     declaredField?: string|null,
+     *     originalField?: string|null,
+     *     inherited?: class-string|null,
+     *     declared?: class-string|null,
      * } $mappingArray
      */
     public static function fromMappingArray(array $mappingArray): self

src/Mapping/FieldMapping.php

@@ -26,7 +26,7 @@ final class FieldMapping implements ArrayAccess
     public bool|null $notInsertable      = null;
     public bool|null $notUpdatable       = null;
     public string|null $columnDefinition = null;
-    /** @psalm-var ClassMetadata::GENERATED_* */
+    /** @psalm-var ClassMetadata::GENERATED_*|null */
     public int|null $generated = null;
     /** @var class-string<BackedEnum>|null */
     public string|null $enumType = null;
@@ -83,7 +83,34 @@ final class FieldMapping implements ArrayAccess
     ) {
     }
 
-    /** @param array{type: string, fieldName: string, columnName: string} $mappingArray */
+    /**
+     * @param array<string, mixed> $mappingArray
+     * @psalm-param array{
+     *     type: string,
+     *     fieldName: string,
+     *     columnName: string,
+     *     length?: int|null,
+     *     id?: bool|null,
+     *     nullable?: bool|null,
+     *     notInsertable?: bool|null,
+     *     notUpdatable?: bool|null,
+     *     columnDefinition?: string|null,
+     *     generated?: ClassMetadata::GENERATED_*|null,
+     *     enumType?: string|null,
+     *     precision?: int|null,
+     *     scale?: int|null,
+     *     unique?: bool|null,
+     *     inherited?: string|null,
+     *     originalClass?: string|null,
+     *     originalField?: string|null,
+     *     quoted?: bool|null,
+     *     declared?: string|null,
+     *     declaredField?: string|null,
+     *     options?: array<string, mixed>|null,
+     *     version?: bool|null,
+     *     default?: string|int|null,
+     * } $mappingArray
+     */
     public static function fromMappingArray(array $mappingArray): self
     {
         $mapping = new self(

src/Mapping/JoinColumnMapping.php

@@ -31,7 +31,17 @@ final class JoinColumnMapping implements ArrayAccess
 
     /**
      * @param array<string, mixed> $mappingArray
-     * @psalm-param array{name: string, referencedColumnName: string, ...} $mappingArray
+     * @psalm-param array{
+     *     name: string,
+     *     referencedColumnName: string,
+     *     unique?: bool|null,
+     *     quoted?: bool|null,
+     *     fieldName?: string|null,
+     *     onDelete?: string|null,
+     *     columnDefinition?: string|null,
+     *     nullable?: bool|null,
+     *     options?: array<string, mixed>|null,
+     * } $mappingArray
      */
     public static function fromMappingArray(array $mappingArray): self
     {

src/Mapping/JoinTableMapping.php

@@ -35,10 +35,10 @@ final class JoinTableMapping implements ArrayAccess
      * @param mixed[] $mappingArray
      * @psalm-param array{
      *    name: string,
-     *    quoted?: bool,
+     *    quoted?: bool|null,
      *    joinColumns?: mixed[],
      *    inverseJoinColumns?: mixed[],
-     *    schema?: string,
+     *    schema?: string|null,
      *    options?: array<string, mixed>
      * } $mappingArray
      */

src/Mapping/ManyToManyOwningSideMapping.php

@@ -41,9 +41,21 @@ final class ManyToManyOwningSideMapping extends ToManyOwningSideMapping implemen
      *     fieldName: string,
      *     sourceEntity: class-string,
      *     targetEntity: class-string,
+     *     cascade?: list<'persist'|'remove'|'detach'|'refresh'|'all'>,
+     *     fetch?: ClassMetadata::FETCH_*|null,
+     *     inherited?: class-string|null,
+     *     declared?: class-string|null,
+     *     cache?: array<mixed>|null,
+     *     id?: bool|null,
+     *     isOnDeleteCascade?: bool|null,
+     *     originalClass?: class-string|null,
+     *     originalField?: string|null,
+     *     orphanRemoval?: bool,
+     *     unique?: bool|null,
      *     joinTable?: mixed[]|null,
      *     type?: int,
-     *     isOwningSide: bool, ...} $mappingArray
+     *     isOwningSide: bool,
+     * } $mappingArray
      */
     public static function fromMappingArrayAndNamingStrategy(array $mappingArray, NamingStrategy $namingStrategy): self
     {

src/Mapping/OneToManyAssociationMapping.php

@@ -12,9 +12,21 @@ final class OneToManyAssociationMapping extends ToManyInverseSideMapping
      *     fieldName: string,
      *     sourceEntity: class-string,
      *     targetEntity: class-string,
+     *     cascade?: list<'persist'|'remove'|'detach'|'refresh'|'all'>,
+     *     fetch?: ClassMetadata::FETCH_*|null,
+     *     inherited?: class-string|null,
+     *     declared?: class-string|null,
+     *     cache?: array<mixed>|null,
+     *     id?: bool|null,
+     *     isOnDeleteCascade?: bool|null,
+     *     originalClass?: class-string|null,
+     *     originalField?: string|null,
+     *     orphanRemoval?: bool,
+     *     unique?: bool|null,
      *     joinTable?: mixed[]|null,
      *     type?: int,
-     *     isOwningSide: bool, ...} $mappingArray
+     *     isOwningSide: bool,
+     * } $mappingArray
      */
     public static function fromMappingArray(array $mappingArray): static
     {
@@ -33,9 +45,21 @@ final class OneToManyAssociationMapping extends ToManyInverseSideMapping
      *     fieldName: string,
      *     sourceEntity: class-string,
      *     targetEntity: class-string,
+     *     cascade?: list<'persist'|'remove'|'detach'|'refresh'|'all'>,
+     *     fetch?: ClassMetadata::FETCH_*|null,
+     *     inherited?: class-string|null,
+     *     declared?: class-string|null,
+     *     cache?: array<mixed>|null,
+     *     id?: bool|null,
+     *     isOnDeleteCascade?: bool|null,
+     *     originalClass?: class-string|null,
+     *     originalField?: string|null,
+     *     orphanRemoval?: bool,
+     *     unique?: bool|null,
      *     joinTable?: mixed[]|null,
      *     type?: int,
-     *     isOwningSide: bool, ...} $mappingArray
+     *     isOwningSide: bool,
+     * } $mappingArray
      */
     public static function fromMappingArrayAndName(array $mappingArray, string $name): static
     {

src/Mapping/ToOneInverseSideMapping.php

@@ -13,8 +13,21 @@ abstract class ToOneInverseSideMapping extends InverseSideMapping
      *     fieldName: string,
      *     sourceEntity: class-string,
      *     targetEntity: class-string,
+     *     cascade?: list<'persist'|'remove'|'detach'|'refresh'|'all'>,
+     *     fetch?: ClassMetadata::FETCH_*|null,
+     *     inherited?: class-string|null,
+     *     declared?: class-string|null,
+     *     cache?: array<mixed>|null,
+     *     id?: bool|null,
+     *     isOnDeleteCascade?: bool|null,
+     *     originalClass?: class-string|null,
+     *     originalField?: string|null,
+     *     orphanRemoval?: bool,
+     *     unique?: bool|null,
+     *     joinTable?: mixed[]|null,
+     *     type?: int,
      *     isOwningSide: bool,
-     *     } $mappingArray
+     * } $mappingArray
      */
     public static function fromMappingArrayAndName(
         array $mappingArray,

src/Mapping/ToOneOwningSideMapping.php

@@ -31,8 +31,22 @@ abstract class ToOneOwningSideMapping extends OwningSideMapping implements ToOne
      *     fieldName: string,
      *     sourceEntity: class-string,
      *     targetEntity: class-string,
+     *     cascade?: list<'persist'|'remove'|'detach'|'refresh'|'all'>,
+     *     fetch?: ClassMetadata::FETCH_*|null,
+     *     inherited?: class-string|null,
+     *     declared?: class-string|null,
+     *     cache?: array<mixed>|null,
+     *     id?: bool|null,
+     *     isOnDeleteCascade?: bool|null,
+     *     originalClass?: class-string|null,
+     *     originalField?: string|null,
+     *     orphanRemoval?: bool,
+     *     unique?: bool|null,
+     *     joinTable?: mixed[]|null,
+     *     type?: int,
+     *     isOwningSide: bool,
      *     joinColumns?: mixed[]|null,
-     *     isOwningSide: bool, ...} $mappingArray
+     * } $mappingArray
      */
     public static function fromMappingArray(array $mappingArray): static
     {
@@ -64,8 +78,22 @@ abstract class ToOneOwningSideMapping extends OwningSideMapping implements ToOne
      *     fieldName: string,
      *     sourceEntity: class-string,
      *     targetEntity: class-string,
+     *     cascade?: list<'persist'|'remove'|'detach'|'refresh'|'all'>,
+     *     fetch?: ClassMetadata::FETCH_*|null,
+     *     inherited?: class-string|null,
+     *     declared?: class-string|null,
+     *     cache?: array<mixed>|null,
+     *     id?: bool|null,
+     *     isOnDeleteCascade?: bool|null,
+     *     originalClass?: class-string|null,
+     *     originalField?: string|null,
+     *     orphanRemoval?: bool,
+     *     unique?: bool|null,
+     *     joinTable?: mixed[]|null,
+     *     type?: int,
+     *     isOwningSide: bool,
      *     joinColumns?: mixed[]|null,
-     *     isOwningSide: bool, ...} $mappingArray
+     * } $mappingArray
      */
     public static function fromMappingArrayAndName(
         array $mappingArray,

src/PersistentCollection.php

@@ -350,11 +350,6 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
         return parent::containsKey($key);
     }
 
-    /**
-     * {@inheritDoc}
-     *
-     * @template TMaybeContained
-     */
     public function contains(mixed $element): bool
     {
         if (! $this->initialized && $this->getMapping()->fetch === ClassMetadata::FETCH_EXTRA_LAZY) {

src/Tools/SchemaValidator.php

@@ -52,18 +52,18 @@ class SchemaValidator
      * It maps built-in Doctrine types to PHP types
      */
     private const BUILTIN_TYPES_MAP = [
-        AsciiStringType::class => 'string',
-        BigIntType::class => 'string',
-        BooleanType::class => 'bool',
-        DecimalType::class => 'string',
-        FloatType::class => 'float',
-        GuidType::class => 'string',
-        IntegerType::class => 'int',
-        JsonType::class => 'array',
-        SimpleArrayType::class => 'array',
-        SmallIntType::class => 'int',
-        StringType::class => 'string',
-        TextType::class => 'string',
+        AsciiStringType::class => ['string'],
+        BigIntType::class => ['int', 'string'],
+        BooleanType::class => ['bool'],
+        DecimalType::class => ['string'],
+        FloatType::class => ['float'],
+        GuidType::class => ['string'],
+        IntegerType::class => ['int'],
+        JsonType::class => ['array'],
+        SimpleArrayType::class => ['array'],
+        SmallIntType::class => ['int'],
+        StringType::class => ['string'],
+        TextType::class => ['string'],
     ];
 
     public function __construct(
@@ -353,21 +353,21 @@ class SchemaValidator
                         $propertyType = $propertyType->getName();
 
                         // If the property type is the same as the metadata field type, we are ok
-                        if ($propertyType === $metadataFieldType) {
+                        if (in_array($propertyType, $metadataFieldType, true)) {
                             return null;
                         }
 
                         if (is_a($propertyType, BackedEnum::class, true)) {
                             $backingType = (string) (new ReflectionEnum($propertyType))->getBackingType();
 
-                            if ($metadataFieldType !== $backingType) {
+                            if (! in_array($backingType, $metadataFieldType, true)) {
                                 return sprintf(
                                     "The field '%s#%s' has the property type '%s' with a backing type of '%s' that differs from the metadata field type '%s'.",
                                     $class->name,
                                     $fieldName,
                                     $propertyType,
                                     $backingType,
-                                    $metadataFieldType,
+                                    implode('|', $metadataFieldType),
                                 );
                             }
 
@@ -392,7 +392,7 @@ class SchemaValidator
                         ) {
                             $backingType = (string) (new ReflectionEnum($fieldMapping->enumType))->getBackingType();
 
-                            if ($metadataFieldType === $backingType) {
+                            if (in_array($backingType, $metadataFieldType, true)) {
                                 return null;
                             }
 
@@ -402,7 +402,7 @@ class SchemaValidator
                                 $fieldName,
                                 $fieldMapping->enumType,
                                 $backingType,
-                                $metadataFieldType,
+                                implode('|', $metadataFieldType),
                             );
                         }
 
@@ -418,7 +418,7 @@ class SchemaValidator
                             $class->name,
                             $fieldName,
                             $propertyType,
-                            $metadataFieldType,
+                            implode('|', $metadataFieldType),
                             $fieldMapping->type,
                         );
                     },
@@ -431,8 +431,10 @@ class SchemaValidator
     /**
      * The exact DBAL type must be used (no subclasses), since consumers of doctrine/orm may have their own
      * customization around field types.
+     *
+     * @return list<string>|null
      */
-    private function findBuiltInType(Type $type): string|null
+    private function findBuiltInType(Type $type): array|null
     {
         $typeName = $type::class;
 

tests/Tests/Models/BigIntegers/BigIntegers.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\Models\BigIntegers;
+
+use Doctrine\DBAL\Types\Types;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class BigIntegers
+{
+    #[ORM\Column]
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    public int|null $id = null;
+
+    #[ORM\Column(type: Types::BIGINT)]
+    public int $one = 1;
+
+    #[ORM\Column(type: Types::BIGINT)]
+    public string $two = '2';
+
+    #[ORM\Column(type: Types::BIGINT)]
+    public float $three = 3.0;
+}

tests/Tests/ORM/Tools/SchemaValidatorTest.php

@@ -25,6 +25,7 @@ use Doctrine\ORM\Mapping\OneToOne;
 use Doctrine\ORM\Mapping\OrderBy;
 use Doctrine\ORM\Mapping\Table;
 use Doctrine\ORM\Tools\SchemaValidator;
+use Doctrine\Tests\Models\BigIntegers\BigIntegers;
 use Doctrine\Tests\Models\ECommerce\ECommerceCart;
 use Doctrine\Tests\OrmTestCase;
 use PHPUnit\Framework\Attributes\DataProvider;
@@ -228,6 +229,16 @@ class SchemaValidatorTest extends OrmTestCase
             $ce,
         );
     }
+
+    public function testBigIntProperty(): void
+    {
+        $class = $this->em->getClassMetadata(BigIntegers::class);
+
+        self::assertSame(
+            ['The field \'Doctrine\Tests\Models\BigIntegers\BigIntegers#three\' has the property type \'float\' that differs from the metadata field type \'int|string\' returned by the \'bigint\' DBAL type.'],
+            $this->validator->validateClass($class),
+        );
+    }
 }
 
 #[MappedSuperclass]