Improve psalm type for "FROM" property (#1077)

vjik · web-flow · commit 78f33cc37d86 · 2025-10-23T15:19:52.000+03:00
x
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -160,7 +160,7 @@
 - Enh #1065: Allow to use table name as a column prefix in update queries (@Tigrov)
 - Enh #1068: Quote string values as column names when join condition is an associative array (@Tigrov)
 - Chg #1070: Change "IndexBy" closure signature to `Closure(array|object):int|string` (@vjik)
-- Enh #1072: Improve psalm types (@vjik)
+- Enh #1072, #1077: Improve psalm types (@vjik)
 - New #1074: Add `ConnectionProvider` class (@Tigrov)
 - Chg #1075: Rename `Query::$join` property to `$joins` (@vjik)
 - New #1076: Allow to use expressions as table name or condition in "join" query methods (@vjik)
diff --git a/src/Command/CommandInterface.php b/src/Command/CommandInterface.php
@@ -31,6 +31,7 @@
  * A command instance is usually created by calling {@see ConnectionInterface::createCommand}.
  *
  * @psalm-import-type ParamsType from ConnectionInterface
+ * @psalm-import-type RawFrom from QueryInterface
  * @psalm-import-type BatchValues from DMLQueryBuilderInterface
  */
 interface CommandInterface
@@ -835,6 +836,7 @@ public function truncateTable(string $table): static;
      * on how to specify FROM part.
      * @param array $params The parameters to bind to the command.
      *
+     * @psalm-param RawFrom|null $from
      * @psalm-param ParamsType $params
      *
      * @throws Exception
diff --git a/src/Helper/DbArrayHelper.php b/src/Helper/DbArrayHelper.php
@@ -17,6 +17,7 @@
 use function array_multisort;
 use function count;
 use function get_object_vars;
+use function gettype;
 use function is_array;
 use function is_string;
 use function iterator_to_array;
@@ -298,12 +299,18 @@ public static function toArray(array|object $object): array
      *  - a string with comma-separated expression values.
      *
      * @return array An array of normalized expressions.
+     *
+     * @psalm-template TArray as array
+     * @psalm-template TExpression as ExpressionInterface
+     * @psalm-param TArray|TExpression|string $raw
+     * @psalm-return ($raw is string ? list<string> : ($raw is ExpressionInterface ? list{TExpression} : TArray))
+     *
+     * @psalm-suppress InvalidFalsableReturnType Psalm cannot correct parse method code.
      */
     public static function normalizeExpressions(array|ExpressionInterface|string $raw): array
     {
         /**
-         * @var array
-         * @psalm-suppress PossiblyInvalidArgument
+         * @psalm-suppress PossiblyInvalidArgument,FalsableReturnStatement
          */
         return match (gettype($raw)) {
             GettypeResult::ARRAY => $raw,
diff --git a/src/Query/Query.php b/src/Query/Query.php
@@ -29,6 +29,7 @@
 use function is_array;
 use function is_int;
 use function is_numeric;
+use function is_scalar;
 use function is_string;
 use function key;
 use function preg_match;
@@ -75,13 +76,15 @@
  * @psalm-import-type IndexBy from QueryInterface
  * @psalm-import-type ResultCallback from QueryInterface
  * @psalm-import-type Join from QueryInterface
+ * @psalm-import-type From from QueryInterface
  */
 class Query implements QueryInterface
 {
     /** @psalm-var SelectValue $select */
     protected array $select = [];
     protected string|null $selectOption = null;
     protected bool $distinct = false;
+    /** @psalm-var From */
     protected array $from = [];
     protected array $groupBy = [];
     protected array|ExpressionInterface|string|null $having = null;
@@ -523,7 +526,6 @@ public function getWithQueries(): array
     public function groupBy(array|string|ExpressionInterface $columns): static
     {
         $this->groupBy = DbArrayHelper::normalizeExpressions($columns);
-
         return $this;
     }
 
@@ -1000,9 +1002,6 @@ private function normalizeSelect(array|bool|float|int|string|ExpressionInterface
             $columns = [$columns];
         }
 
-        /**
-         * @var SelectValue
-         */
         $columns = DbArrayHelper::normalizeExpressions($columns);
 
         $select = [];
diff --git a/src/Query/QueryInterface.php b/src/Query/QueryInterface.php
@@ -33,6 +33,8 @@
  * @psalm-type JoinTable = array<string, ExpressionInterface|string>|ExpressionInterface|string
  * @psalm-type JoinOn = array<ExpressionInterface|string>|ExpressionInterface|string
  * @psalm-type Join = list{string, JoinTable, JoinOn}
+ * @psalm-type From = array<string|ExpressionInterface>
+ * @psalm-type RawFrom = array<string|ExpressionInterface>|ExpressionInterface|string
  * @psalm-import-type ParamsType from ConnectionInterface
  * @psalm-import-type SelectValue from QueryPartsInterface
  */
diff --git a/src/Query/QueryPartsInterface.php b/src/Query/QueryPartsInterface.php
@@ -22,6 +22,7 @@
  * @psalm-import-type JoinTable from QueryInterface
  * @psalm-import-type JoinOn from QueryInterface
  * @psalm-import-type Join from QueryInterface
+ * @psalm-import-type RawFrom from QueryInterface
  */
 interface QueryPartsInterface
 {
@@ -326,6 +327,8 @@ public function setFor(string|array|null $value): static;
      * $subQuery = "(SELECT * FROM `user` WHERE `active` = 1)";
      * $query = (new \Yiisoft\Db\Query\Query)->from(['activeusers' => $subQuery]);
      * ```
+     *
+     * @psalm-param RawFrom $tables
      */
     public function from(array|ExpressionInterface|string $tables): static;
 
diff --git a/src/QueryBuilder/DMLQueryBuilderInterface.php b/src/QueryBuilder/DMLQueryBuilderInterface.php
@@ -19,6 +19,7 @@
  * @link https://en.wikipedia.org/wiki/Data_manipulation_language
  *
  * @psalm-import-type ParamsType from ConnectionInterface
+ * @psalm-import-type RawFrom from QueryInterface
  * @psalm-type BatchValues = iterable<iterable<array-key, mixed>>
  */
 interface DMLQueryBuilderInterface
@@ -190,6 +191,7 @@ public function resetSequence(string $table, int|string|null $value = null): str
      *
      * @return string The UPDATE SQL.
      *
+     * @psalm-param RawFrom|null $from
      * @psalm-param ParamsType $params
      *
      * Note: The method will escape the table and column names.

Original file line number	Diff line number	Diff line change
`@@ -31,6 +31,7 @@`
`31`	`31`	`* A command instance is usually created by calling {@see ConnectionInterface::createCommand}.`
`32`	`32`	`*`
`33`	`33`	`* @psalm-import-type ParamsType from ConnectionInterface`
	`34`	`+ * @psalm-import-type RawFrom from QueryInterface`
`34`	`35`	`* @psalm-import-type BatchValues from DMLQueryBuilderInterface`
`35`	`36`	`*/`
`36`	`37`	`interface CommandInterface`
`@@ -835,6 +836,7 @@ public function truncateTable(string $table): static;`
`835`	`836`	`* on how to specify FROM part.`
`836`	`837`	`* @param array $params The parameters to bind to the command.`
`837`	`838`	`*`
	`839`	`+ * @psalm-param RawFrom\|null $from`
`838`	`840`	`* @psalm-param ParamsType $params`
`839`	`841`	`*`
`840`	`842`	`* @throws Exception`
Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@`
`19`	`19`	`* @link https://en.wikipedia.org/wiki/Data_manipulation_language`
`20`	`20`	`*`
`21`	`21`	`* @psalm-import-type ParamsType from ConnectionInterface`
	`22`	`+ * @psalm-import-type RawFrom from QueryInterface`
`22`	`23`	`* @psalm-type BatchValues = iterable<iterable<array-key, mixed>>`
`23`	`24`	`*/`
`24`	`25`	`interface DMLQueryBuilderInterface`
`@@ -190,6 +191,7 @@ public function resetSequence(string $table, int\|string\|null $value = null): str`
`190`	`191`	`*`
`191`	`192`	`* @return string The UPDATE SQL.`
`192`	`193`	`*`
	`194`	`+ * @psalm-param RawFrom\|null $from`
`193`	`195`	`* @psalm-param ParamsType $params`
`194`	`196`	`*`
`195`	`197`	`* Note: The method will escape the table and column names.`