Merge branch '2.13.x' into 3.0.x

* 2.13.x:
  Make phpdoc more precise
  Deprecate setting fetch mode to random integers
  Prepare split of output walkers and tree walkers (doctrine#9786)
  PHPStan 1.7.0 (doctrine#9785)
  Deprecate passing null to Query::setDQL()
  Kill call_user_func(_array) (doctrine#9780)
  Fix wrong types for AbstractQuery and child classes (doctrine#9774)
  Document callable as possible
  Remove override phpdoc tag
  Add use statement (doctrine#9769)

UPGRADE.md

@@ -385,6 +385,84 @@ Use `toIterable()` instead.
 
 # Upgrade to 2.13
 
+## Deprecated passing invalid fetch modes to `AbstractQuery::setFetchMode()`
+
+Calling `AbstractQuery::setFetchMode()` with anything else than
+`Doctrine\ORM\Mapping::FETCH_EAGER` results in
+`Doctrine\ORM\Mapping::FETCH_LAZY` being used. Relying on that behavior is
+deprecated and will result in an exception in 3.0.
+
+## Prepare split of output walkers and tree walkers
+
+In 3.0, `SqlWalker` and its child classes won't implement the `TreeWalker`
+interface anymore. Relying on that inheritance is deprecated.
+
+The following methods of the `TreeWalker` interface have been deprecated:
+
+* `setQueryComponent()`
+* `walkSelectClause()`
+* `walkFromClause()`
+* `walkFunction()`
+* `walkOrderByClause()`
+* `walkOrderByItem()`
+* `walkHavingClause()`
+* `walkJoin()`
+* `walkSelectExpression()`
+* `walkQuantifiedExpression()`
+* `walkSubselect()`
+* `walkSubselectFromClause()`
+* `walkSimpleSelectClause()`
+* `walkSimpleSelectExpression()`
+* `walkAggregateExpression()`
+* `walkGroupByClause()`
+* `walkGroupByItem()`
+* `walkDeleteClause()`
+* `walkUpdateClause()`
+* `walkUpdateItem()`
+* `walkWhereClause()`
+* `walkConditionalExpression()`
+* `walkConditionalTerm()`
+* `walkConditionalFactor()`
+* `walkConditionalPrimary()`
+* `walkExistsExpression()`
+* `walkCollectionMemberExpression()`
+* `walkEmptyCollectionComparisonExpression()`
+* `walkNullComparisonExpression()`
+* `walkInExpression()`
+* `walkInstanceOfExpression()`
+* `walkLiteral()`
+* `walkBetweenExpression()`
+* `walkLikeExpression()`
+* `walkStateFieldPathExpression()`
+* `walkComparisonExpression()`
+* `walkInputParameter()`
+* `walkArithmeticExpression()`
+* `walkArithmeticTerm()`
+* `walkStringPrimary()`
+* `walkArithmeticFactor()`
+* `walkSimpleArithmeticExpression()`
+* `walkPathExpression()`
+* `walkResultVariable()`
+* `getExecutor()`
+
+The following changes have been made to the abstract `TreeWalkerAdapter` class:
+
+* All implementations of now-deprecated `TreeWalker` methods have been
+  deprecated as well.
+* The method `setQueryComponent()` will become protected in 3.0. Calling it
+  publicly is deprecated.
+* The method `_getQueryComponents()` is deprecated, call `getQueryComponents()`
+  instead.
+
+On the `TreeWalkerChain` class, all implementations of now-deprecated
+`TreeWalker` methods have been deprecated as well.  However, `SqlWalker` is
+unaffected by those deprecations and will continue to implement all of those
+methods.
+
+## Deprecated passing `null` to `Doctrine\ORM\Query::setDQL()`
+
+Doing `$query->setDQL(null);` achieves nothing.
+
 ## Deprecated omitting second argument to `NamingStrategy::joinColumnName`
 
 When implementing `NamingStrategy`, it is deprecated to implement

composer.json

@@ -39,7 +39,7 @@
         "doctrine/annotations": "^1.13",
         "doctrine/coding-standard": "^9.0",
         "phpbench/phpbench": "^1.0",
-        "phpstan/phpstan": "1.6.3",
+        "phpstan/phpstan": "1.7.0",
         "phpunit/phpunit": "^9.5",
         "psr/log": "^1 || ^2 || ^3",
         "squizlabs/php_codesniffer": "3.6.2",

docs/en/reference/php-mapping.rst

@@ -19,6 +19,8 @@ to use the ``StaticPHPDriver``:
 .. code-block:: php
 
     <?php
+    use Doctrine\Persistence\Mapping\Driver\StaticPHPDriver;
+
     $driver = new StaticPHPDriver('/path/to/entities');
     $em->getConfiguration()->setMetadataDriverImpl($driver);
 

lib/Doctrine/ORM/AbstractQuery.php

@@ -11,6 +11,7 @@
 use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Cache\QueryCacheProfile;
 use Doctrine\DBAL\Result;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\Logging\CacheLogger;
 use Doctrine\ORM\Cache\QueryCacheKey;
 use Doctrine\ORM\Cache\TimestampCacheKey;
@@ -27,10 +28,12 @@
 use function array_shift;
 use function assert;
 use function count;
+use function in_array;
 use function is_array;
 use function is_numeric;
 use function is_object;
 use function is_scalar;
+use function is_string;
 use function iterator_count;
 use function iterator_to_array;
 use function ksort;
@@ -276,7 +279,7 @@ public function setCacheMode($cacheMode)
      * The returned SQL syntax depends on the connection driver that is used
      * by this query object at the time of this method call.
      *
-     * @return string SQL query
+     * @return list<string>|string SQL query
      */
     abstract public function getSQL();
 
@@ -318,7 +321,7 @@ public function getParameters()
     /**
      * Gets a query parameter.
      *
-     * @param mixed $key The key (index or name) of the bound parameter.
+     * @param int|string $key The key (index or name) of the bound parameter.
      *
      * @return Parameter|null The value of the bound parameter, or NULL if not available.
      */
@@ -347,7 +350,6 @@ static function (Query\Parameter $parameter) use ($key): bool {
      */
     public function setParameters($parameters)
     {
-        // BC compatibility with 2.3-
         if (is_array($parameters)) {
             /** @psalm-var ArrayCollection<int, Parameter> $parameterCollection */
             $parameterCollection = new ArrayCollection();
@@ -395,8 +397,8 @@ public function setParameter($key, $value, $type = null)
      *
      * @param mixed $value
      *
-     * @return mixed[]|string|int|float|bool
-     * @psalm-return array|scalar
+     * @return mixed[]|string|int|float|bool|object|null
+     * @psalm-return array|scalar|object|null
      *
      * @throws ORMInvalidArgumentException
      */
@@ -709,17 +711,22 @@ public function getQueryCacheProfile()
     /**
      * Change the default fetch mode of an association for this query.
      *
-     * $fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY
-     *
-     * @param string $class
-     * @param string $assocName
-     * @param int    $fetchMode
+     * @param class-string $class
+     * @param string       $assocName
+     * @param int          $fetchMode
+     * @psalm-param Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode
      *
      * @return $this
      */
     public function setFetchMode($class, $assocName, $fetchMode)
     {
-        if ($fetchMode !== Mapping\ClassMetadata::FETCH_EAGER) {
+        if (! in_array($fetchMode, [Mapping\ClassMetadata::FETCH_EAGER, Mapping\ClassMetadata::FETCH_LAZY], true)) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9777',
+                'Calling %s() with something else than ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY is deprecated.',
+                __METHOD__
+            );
             $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
         }
 
@@ -1147,7 +1154,8 @@ protected function getHydrationCacheId()
             $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
         }
 
-        $sql                    = $this->getSQL();
+        $sql = $this->getSQL();
+        assert(is_string($sql));
         $queryCacheProfile      = $this->getHydrationCacheProfile();
         $hints                  = $this->getHints();
         $hints['hydrationMode'] = $this->getHydrationMode();
@@ -1207,7 +1215,8 @@ public function __clone()
      */
     protected function getHash()
     {
-        $query  = $this->getSQL();
+        $query = $this->getSQL();
+        assert(is_string($query));
         $hints  = $this->getHints();
         $params = array_map(function (Parameter $parameter) {
             $value = $parameter->getValue();

lib/Doctrine/ORM/Configuration.php

@@ -16,6 +16,7 @@
 use Doctrine\ORM\Mapping\NamingStrategy;
 use Doctrine\ORM\Mapping\QuoteStrategy;
 use Doctrine\ORM\Proxy\ProxyFactory;
+use Doctrine\ORM\Query\AST\Functions\FunctionNode;
 use Doctrine\ORM\Query\Filter\SQLFilter;
 use Doctrine\ORM\Repository\DefaultRepositoryFactory;
 use Doctrine\ORM\Repository\RepositoryFactory;
@@ -195,8 +196,9 @@ public function setMetadataCache(CacheItemPoolInterface $cache): void
      *
      * DQL function names are case-insensitive.
      *
-     * @param string          $name      Function name.
-     * @param string|callable $className Class name or a callable that returns the function.
+     * @param string                $name      Function name.
+     * @param class-string|callable $className Class name or a callable that returns the function.
+     * @psalm-param class-string<FunctionNode>|callable(string):FunctionNode $className
      *
      * @return void
      */
@@ -211,7 +213,7 @@ public function addCustomStringFunction($name, $className)
      * @param string $name
      *
      * @return string|null
-     * @psalm-return ?class-string
+     * @psalm-return class-string<FunctionNode>|callable(string):FunctionNode|null
      */
     public function getCustomStringFunction($name)
     {
@@ -228,7 +230,7 @@ public function getCustomStringFunction($name)
      *
      * Any previously added string functions are discarded.
      *
-     * @psalm-param array<string, class-string> $functions The map of custom
+     * @psalm-param array<string, class-string<FunctionNode>|callable(string):FunctionNode> $functions The map of custom
      *                                                     DQL string functions.
      *
      * @return void

lib/Doctrine/ORM/NativeQuery.php

@@ -33,12 +33,8 @@ public function setSQL($sql): self
 
     /**
      * Gets the SQL query.
-     *
-     * @return mixed The built SQL query or an array of all SQL queries.
-     *
-     * @override
      */
-    public function getSQL()
+    public function getSQL(): string
     {
         return $this->sql;
     }

lib/Doctrine/ORM/Persisters/Collection/OneToManyPersister.php

@@ -14,7 +14,9 @@
 use function array_merge;
 use function array_reverse;
 use function array_values;
+use function assert;
 use function implode;
+use function is_string;
 
 /**
  * Persister for one-to-many collections.
@@ -206,7 +208,9 @@ private function deleteJoinedEntityCollection(PersistentCollection $collection):
             . ' FROM ' . $targetClass->name . ' t0 WHERE t0.' . $mapping['mappedBy'] . ' = :owner'
         )->setParameter('owner', $collection->getOwner());
 
-        $statement  = 'INSERT INTO ' . $tempTable . ' (' . $idColumnList . ') ' . $query->getSQL();
+        $sql = $query->getSQL();
+        assert(is_string($sql));
+        $statement  = 'INSERT INTO ' . $tempTable . ' (' . $idColumnList . ') ' . $sql;
         $parameters = array_values($sourceClass->getIdentifierValues($collection->getOwner()));
         $numDeleted = $this->conn->executeStatement($statement, $parameters);
 

lib/Doctrine/ORM/Persisters/Entity/JoinedSubclassPersister.php

@@ -66,8 +66,6 @@ private function getVersionedClassMetadata(): ClassMetadata
 
     /**
      * Gets the name of the table that owns the column the given field is mapped to.
-     *
-     * @override
      */
     public function getOwningTable(string $fieldName): string
     {

lib/Doctrine/ORM/Query.php

@@ -6,6 +6,7 @@
 
 use Doctrine\DBAL\LockMode;
 use Doctrine\DBAL\Types\Type;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Query\AST\DeleteStatement;
 use Doctrine\ORM\Query\AST\SelectStatement;
@@ -111,6 +112,7 @@ final class Query extends AbstractQuery
      * The current state of this query.
      *
      * @var int
+     * @psalm-var self::STATE_*
      */
     private $_state = self::STATE_DIRTY;
 
@@ -166,7 +168,7 @@ final class Query extends AbstractQuery
     /**
      * The query cache lifetime.
      *
-     * @var int
+     * @var int|null
      */
     private $queryCacheTTL;
 
@@ -180,9 +182,7 @@ final class Query extends AbstractQuery
     /**
      * Gets the SQL query/queries that correspond to this DQL query.
      *
-     * @return mixed The built sql query or an array of all sql queries.
-     *
-     * @override
+     * @return list<string>|string The built sql query or an array of all sql queries.
      */
     public function getSQL()
     {
@@ -524,9 +524,6 @@ public function getExpireQueryCache(): bool
         return $this->expireQueryCache;
     }
 
-    /**
-     * @override
-     */
     public function free(): void
     {
         parent::free();
@@ -538,15 +535,24 @@ public function free(): void
     /**
      * Sets a DQL query string.
      *
-     * @param string $dqlQuery DQL Query.
+     * @param string|null $dqlQuery DQL Query.
      */
     public function setDQL($dqlQuery): self
     {
-        if ($dqlQuery !== null) {
-            $this->dql    = $dqlQuery;
-            $this->_state = self::STATE_DIRTY;
+        if ($dqlQuery === null) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9784',
+                'Calling %s with null is deprecated and will result in a TypeError in Doctrine 3.0',
+                __METHOD__
+            );
+
+            return $this;
         }
 
+        $this->dql    = $dqlQuery;
+        $this->_state = self::STATE_DIRTY;
+
         return $this;
     }
 
@@ -567,6 +573,7 @@ public function getDQL(): ?string
      * @see AbstractQuery::STATE_DIRTY
      *
      * @return int The query state.
+     * @psalm-return self::STATE_* The query state.
      */
     public function getState(): int
     {

lib/Doctrine/ORM/Query/AST/Functions/AbsFunction.php

@@ -20,7 +20,6 @@ class AbsFunction extends FunctionNode
     public $simpleArithmeticExpression;
 
     /**
-     * @override
      * @inheritdoc
      */
     public function getSql(SqlWalker $sqlWalker)
@@ -31,7 +30,6 @@ public function getSql(SqlWalker $sqlWalker)
     }
 
     /**
-     * @override
      * @inheritdoc
      */
     public function parse(Parser $parser)