Improve psalm types for scalar values in select

yiisoft · Apr 7, 2024 · fa0ebae · fa0ebae
1 parent 4c3b3c0
commit fa0ebae
Show file tree

Hide file tree

Showing 5 changed files with 27 additions and 2 deletions.
diff --git a/src/Query/Query.php b/src/Query/Query.php
@@ -67,9 +67,14 @@
  * ```
  *
  * Query internally uses the {@see \Yiisoft\Db\QueryBuilder\AbstractQueryBuilder} class to generate the SQL statement.
+ *
+ * @psalm-import-type SelectValue from QueryPartsInterface
  */
 class Query implements QueryInterface
 {
+    /**
+     * @psalm-var SelectValue $select
+     */
     protected array $select = [];
     protected string|null $selectOption = null;
     protected bool|null $distinct = null;
@@ -179,6 +184,9 @@ public function andHaving(array|string|ExpressionInterface $condition, array $pa
         return $this;
     }
 
+    /**
+     * @psalm-param SelectValue|scalar|ExpressionInterface $columns
+     */
     public function addSelect(array|bool|float|int|string|ExpressionInterface $columns): static
     {
         if ($this->select === []) {
@@ -855,6 +863,9 @@ private function normalizeOrderBy(array|string|ExpressionInterface $columns): ar
 
     /**
      * Normalizes the `SELECT` columns passed to {@see select()} or {@see addSelect()}.
+     *
+     * @psalm-param SelectValue|scalar|ExpressionInterface $columns
+     * @psalm-return SelectValue
      */
     private function normalizeSelect(array|bool|float|int|string|ExpressionInterface $columns): array
     {
@@ -866,7 +877,6 @@ private function normalizeSelect(array|bool|float|int|string|ExpressionInterface
 
         $select = [];
 
-        /** @psalm-var array<array-key, bool|float|int|string|ExpressionInterface> $columns */
         foreach ($columns as $columnAlias => $columnDefinition) {
             if (is_string($columnAlias)) {
                 // Already in the normalized format, good for them.

diff --git a/src/Query/QueryInterface.php b/src/Query/QueryInterface.php
@@ -28,6 +28,7 @@
  * Sorting is supported via {@see orderBy()} and items can be limited to match some conditions using {@see where()}.
  *
  * @psalm-import-type ParamsType from ConnectionInterface
+ * @psalm-import-type SelectValue from QueryPartsInterface
  */
 interface QueryInterface extends ExpressionInterface, QueryPartsInterface, QueryFunctionsInterface
 {
@@ -207,6 +208,7 @@ public function getParams(): array;
 
     /**
      * @return array The "select" value.
+     * @psalm-return SelectValue
      */
     public function getSelect(): array;
 

diff --git a/src/Query/QueryPartsInterface.php b/src/Query/QueryPartsInterface.php
@@ -15,6 +15,7 @@
  *
  * {@see Query} uses these methods to build and manipulate SQL statements.
  *
+ * @psalm-type SelectValue = array<array-key, ExpressionInterface|scalar>
  * @psalm-import-type ParamsType from ConnectionInterface
  */
 interface QueryPartsInterface
@@ -69,6 +70,8 @@ public function addOrderBy(array|string|ExpressionInterface $columns): static;
      * @see select() for more details about the format of this parameter.
      *
      * @since 2.0.0 `$columns` can be a scalar value or an array of scalar values.
+     *
+     * @psalm-param SelectValue|scalar|ExpressionInterface $columns
      */
     public function addSelect(array|bool|float|int|string|ExpressionInterface $columns): static;
 
@@ -532,6 +535,8 @@ public function rightJoin(array|string $table, array|string $on = '', array $par
      *
      * @since 2.0.0 `$columns` can be a scalar value or an array of scalar values.
      * For example, `$query->select(1)` will be converted to `SELECT 1`.
+     *
+     * @psalm-param SelectValue|scalar|ExpressionInterface $columns
      */
     public function select(array|bool|float|int|string|ExpressionInterface $columns, string $option = null): static;
 

diff --git a/src/QueryBuilder/AbstractDQLQueryBuilder.php b/src/QueryBuilder/AbstractDQLQueryBuilder.php
@@ -15,6 +15,7 @@
 use Yiisoft\Db\Expression\ExpressionBuilderInterface;
 use Yiisoft\Db\Expression\ExpressionInterface;
 use Yiisoft\Db\Helper\DbStringHelper;
+use Yiisoft\Db\Query\QueryPartsInterface;
 use Yiisoft\Db\QueryBuilder\Condition\HashCondition;
 use Yiisoft\Db\QueryBuilder\Condition\Interface\ConditionInterface;
 use Yiisoft\Db\QueryBuilder\Condition\SimpleCondition;
@@ -43,6 +44,8 @@
  * It's used to query data from a database.
  *
  * @link https://en.wikipedia.org/wiki/Data_query_language
+ *
+ * @psalm-import-type SelectValue from QueryPartsInterface
  */
 abstract class AbstractDQLQueryBuilder implements DQLQueryBuilderInterface
 {
@@ -332,6 +335,9 @@ public function buildOrderByAndLimit(
         return $sql;
     }
 
+    /**
+     * @psalm-param SelectValue $columns
+     */
     public function buildSelect(
         array $columns,
         array &$params,
@@ -348,7 +354,6 @@ public function buildSelect(
             return $select . ' *';
         }
 
-        /** @psalm-var array<array-key, ExpressionInterface|bool|float|int|string> $columns */
         foreach ($columns as $i => $column) {
             if ($column instanceof ExpressionInterface) {
                 if (is_int($i)) {

diff --git a/src/QueryBuilder/DQLQueryBuilderInterface.php b/src/QueryBuilder/DQLQueryBuilderInterface.php
@@ -11,6 +11,7 @@
 use Yiisoft\Db\Exception\NotSupportedException;
 use Yiisoft\Db\Expression\ExpressionBuilderInterface;
 use Yiisoft\Db\Expression\ExpressionInterface;
+use Yiisoft\Db\Query\QueryPartsInterface;
 use Yiisoft\Db\QueryBuilder\Condition\Interface\ConditionInterface;
 use Yiisoft\Db\Query\QueryInterface;
 
@@ -20,6 +21,7 @@
  * @link https://en.wikipedia.org/wiki/Data_query_language
  *
  * @psalm-import-type ParamsType from ConnectionInterface
+ * @psalm-import-type SelectValue from QueryPartsInterface
  */
 interface DQLQueryBuilderInterface
 {
@@ -224,6 +226,7 @@ public function buildOrderByAndLimit(
      *
      * @return string The `SELECT` clause built from {@see \Yiisoft\Db\Query\Query::select()}.
      *
+     * @psalm-param SelectValue $columns
      * @psalm-param ParamsType $params
      */
     public function buildSelect(