Merge branch '2.11.x' into 3.0.x

* 2.11.x:
  PHPStan 1.3.3, Psalm 4.18.1
  Remove Psalm job for analyzing DBAL 2
  Use the readonly annotation (doctrine#9340)
  Add support for custom types with requireSQLConversion and ResultSetMappingBuilder::generateSelectClause()
  PSR-6 second level cache
  Fix type errors in AbstractQuery and QueryBuilder (doctrine#9275)
  Mark columnName as always set
  Add support for PHP 8.1 enums.
  Remove ignore rules for issues fixed upstream (doctrine#9336)
  [doctrineGH-9277] deprecate php driver (doctrine#9309)

Author: derrabus

.github/workflows/static-analysis.yml

@@ -54,8 +54,6 @@ jobs:
       matrix:
         php-version:
           - "8.1"
-        dbal-version:
-          - "default"
 
     steps:
       - name: "Checkout code"
@@ -67,10 +65,6 @@ jobs:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
 
-      - name: "Require specific DBAL version"
-        run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
-        if: "${{ matrix.dbal-version != 'default' }}"
-
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
         with:

UPGRADE.md

@@ -107,6 +107,31 @@ Use `toIterable()` instead.
 
 # Upgrade to 2.11
 
+## PSR-6-based second level cache
+
+The second level cache has been reworked to consume a PSR-6 cache. Using a
+Doctrine Cache instance is deprecated.
+
+* `DefaultCacheFactory`: The constructor expects a PSR-6 cache item pool as
+  second argument now.
+* `DefaultMultiGetRegion`: This class is deprecated in favor of `DefaultRegion`.
+* `DefaultRegion`:
+  * The constructor expects a PSR-6 cache item pool as second argument now.
+  * The protected `$cache` property is deprecated.
+  * The properties `$name` and `$lifetime` as well as the constant
+   `REGION_KEY_SEPARATOR` and the method `getCacheEntryKey()` are flagged as
+   `@internal` now. They all will become `private` in 3.0.
+  * The method `getCache()` is deprecated without replacement.
+
+## Deprecated: `Doctrine\ORM\Mapping\Driver\PHPDriver`
+
+Use `StaticPHPDriver` instead when you want to programmatically configure
+entity metadata.
+
+You can convert mappings with the `orm:convert-mapping` command or more simply
+in this case, `include` the metadata file from the `loadMetadata` static method
+used by the `StaticPHPDriver`.
+
 ## Deprecated: `Setup::registerAutoloadDirectory()`
 
 Use Composer's autoloader instead.

composer.json

@@ -41,11 +41,11 @@
         "doctrine/annotations": "^1.13",
         "doctrine/coding-standard": "^9.0",
         "phpbench/phpbench": "^1.0",
-        "phpstan/phpstan": "1.3.0",
+        "phpstan/phpstan": "1.3.3",
         "phpunit/phpunit": "^9.5",
         "squizlabs/php_codesniffer": "3.6.2",
         "symfony/cache": "^4.4 || ^5.4 || ^6.0",
-        "vimeo/psalm": "4.17.0"
+        "vimeo/psalm": "4.18.1"
     },
     "conflict": {
         "doctrine/annotations": "<1.13 || >= 2.0"

docs/en/reference/basic-mapping.rst

@@ -172,6 +172,8 @@ list:
   unique key.
 - ``nullable``: (optional, default FALSE) Whether the database
   column is nullable.
+- ``enumType``: (optional, requires PHP 8.1 and ORM 2.11) The PHP enum type
+  name to convert the database value into.
 - ``precision``: (optional, default 0) The precision for a decimal
   (exact numeric) column (applies only for decimal column),
   which is the maximum number of digits that are stored for the values.
@@ -206,6 +208,9 @@ Additionally, Doctrine will map PHP types to ``type`` attribute as follows:
 - ``int``: ``integer``
 - ``string`` or any other type: ``string``
 
+As of version 2.11 Doctrine can also automatically map typed properties using a
+PHP 8.1 enum to set the right ``type`` and ``enumType``.
+
 .. _reference-mapping-types:
 
 Doctrine Mapping Types

docs/en/reference/php-mapping.rst

@@ -249,5 +249,3 @@ themselves.
 -  ``setIdentifierValues($entity, $id)``
 -  ``setFieldValue($entity, $field, $value)``
 -  ``getFieldValue($entity, $field)``
-
-

docs/en/reference/second-level-cache.rst

@@ -172,7 +172,7 @@ To enable the second-level-cache, you should provide a cache factory.
 
     <?php
     /** @var \Doctrine\ORM\Cache\RegionsConfiguration $cacheConfig */
-    /** @var \Doctrine\Common\Cache\Cache $cache */
+    /** @var \Psr\Cache\CacheItemPoolInterface $cache */
     /** @var \Doctrine\ORM\Configuration $config */
 
     $factory = new \Doctrine\ORM\Cache\DefaultCacheFactory($cacheConfig, $cache);

doctrine-mapping.xsd

@@ -299,6 +299,7 @@
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <xs:attribute name="nullable" type="xs:boolean" default="false" />
+    <xs:attribute name="enum-type" type="xs:string" />
     <xs:attribute name="version" type="xs:boolean" />
     <xs:attribute name="column-definition" type="xs:string" />
     <xs:attribute name="precision" type="xs:integer" use="optional" />

lib/Doctrine/ORM/AbstractQuery.php

@@ -19,6 +19,7 @@
 use Doctrine\ORM\Query\QueryException;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\Persistence\Mapping\MappingException;
+use LogicException;
 use Psr\Cache\CacheItemPoolInterface;
 use Traversable;
 
@@ -87,7 +88,7 @@ abstract class AbstractQuery
     /**
      * The user-specified ResultSetMapping to use.
      *
-     * @var ResultSetMapping
+     * @var ResultSetMapping|null
      */
     protected $_resultSetMapping;
 
@@ -109,6 +110,7 @@ abstract class AbstractQuery
      * The hydration mode.
      *
      * @var string|int
+     * @psalm-var string|AbstractQuery::HYDRATE_*
      */
     protected $_hydrationMode = self::HYDRATE_OBJECT;
 
@@ -146,6 +148,7 @@ abstract class AbstractQuery
      * Second level query cache mode.
      *
      * @var int|null
+     * @psalm-var Cache::MODE_*|null
      */
     protected $cacheMode;
 
@@ -247,7 +250,8 @@ public function setLifetime($lifetime)
     }
 
     /**
-     * @return int
+     * @return int|null
+     * @psalm-return Cache::MODE_*|null
      */
     public function getCacheMode()
     {
@@ -256,6 +260,7 @@ public function getCacheMode()
 
     /**
      * @param int $cacheMode
+     * @psalm-param Cache::MODE_* $cacheMode
      *
      * @return $this
      */
@@ -488,7 +493,7 @@ public function setResultSetMapping(Query\ResultSetMapping $rsm)
     /**
      * Gets the ResultSetMapping used for hydration.
      *
-     * @return ResultSetMapping
+     * @return ResultSetMapping|null
      */
     protected function getResultSetMapping()
     {
@@ -791,6 +796,7 @@ public function setFetchMode($class, $assocName, $fetchMode)
      *
      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
      *                                  One of the Query::HYDRATE_* constants.
+     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
      * @return $this
      */
@@ -805,6 +811,7 @@ public function setHydrationMode($hydrationMode)
      * Gets the hydration mode currently used by the query.
      *
      * @return string|int
+     * @psalm-return string|AbstractQuery::HYDRATE_*
      */
     public function getHydrationMode()
     {
@@ -817,6 +824,7 @@ public function getHydrationMode()
      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
      *
      * @param string|int $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
      * @return mixed
      */
@@ -864,7 +872,8 @@ public function getScalarResult()
     /**
      * Get exactly one result or null.
      *
-     * @param string|int $hydrationMode
+     * @param string|int|null $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
      *
      * @return mixed
      *
@@ -901,7 +910,8 @@ public function getOneOrNullResult($hydrationMode = null)
      * If the result is not unique, a NonUniqueResultException is thrown.
      * If there is no result, a NoResultException is thrown.
      *
-     * @param string|int $hydrationMode
+     * @param string|int|null $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
      *
      * @return mixed
      *
@@ -998,6 +1008,7 @@ public function getHints()
      * @param ArrayCollection|array|mixed[] $parameters    The query parameters.
      * @param string|int|null               $hydrationMode The hydration mode to use.
      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null    $hydrationMode
      *
      * @return iterable<mixed>
      */
@@ -1015,6 +1026,9 @@ public function toIterable(iterable $parameters = [], $hydrationMode = null): it
         }
 
         $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
 
         if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
             throw QueryException::iterateWithMixedResultNotAllowed();
@@ -1031,6 +1045,7 @@ public function toIterable(iterable $parameters = [], $hydrationMode = null): it
      * @param ArrayCollection|mixed[]|null $parameters    Query parameters.
      * @param string|int|null              $hydrationMode Processing mode to be used during the hydration process.
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
@@ -1049,6 +1064,7 @@ public function execute($parameters = null, $hydrationMode = null)
      * @param ArrayCollection|mixed[]|null $parameters
      * @param string|int|null              $hydrationMode
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
@@ -1093,7 +1109,11 @@ private function executeIgnoreQueryCache($parameters = null, $hydrationMode = nu
             return $stmt;
         }
 
-        $rsm  = $this->getResultSetMapping();
+        $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
+
         $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
 
         $setCacheEntry($data);
@@ -1117,12 +1137,17 @@ private function getHydrationCache(): CacheItemPoolInterface
      * @param ArrayCollection|mixed[]|null $parameters
      * @param string|int|null              $hydrationMode
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
     private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
     {
-        $rsm        = $this->getResultSetMapping();
+        $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
+
         $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
         $queryKey   = new QueryCacheKey(
             $this->getHash(),
@@ -1157,6 +1182,7 @@ private function executeUsingQueryCache($parameters = null, $hydrationMode = nul
 
     private function getTimestampKey(): ?TimestampCacheKey
     {
+        assert($this->_resultSetMapping !== null);
         $entityName = reset($this->_resultSetMapping->aliasMap);
 
         if (empty($entityName)) {

lib/Doctrine/ORM/Cache/AssociationCacheEntry.php

@@ -10,15 +10,13 @@
 class AssociationCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
-     *
+     * @readonly Public only for performance reasons, it should be considered immutable.
      * @var array<string, mixed> The entity identifier
      */
     public $identifier;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
-     *
+     * @readonly Public only for performance reasons, it should be considered immutable.
      * @var string The entity class name
      */
     public $class;

lib/Doctrine/ORM/Cache/CacheKey.php

@@ -11,8 +11,7 @@
 abstract class CacheKey
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
-     *
+     * @readonly Public only for performance reasons, it should be considered immutable.
      * @var string Unique identifier
      */
     public $hash;