From dd4c091e665d704d18f5ff1f7d4765ede0cb4020 Mon Sep 17 00:00:00 2001
From: Maksim Spirkov <63721828+mspirkov@users.noreply.github.com>
Date: Sat, 25 Oct 2025 22:19:58 +0300
Subject: [PATCH] Fix #20634: Fix PHPDoc annotations in `yii\db` namespace. Add
 PHPStan/Psalm annotations for `yii\db\SqlTokenizer::startsWithAnyLongest()`

---
 framework/CHANGELOG.md                        | 1 +
 framework/base/DynamicModel.php               | 2 +-
 framework/db/ActiveRelationTrait.php          | 2 +-
 framework/db/ColumnSchema.php                 | 2 +-
 framework/db/QueryBuilder.php                 | 1 +
 framework/db/SqlTokenizer.php                 | 6 +++++-
 framework/db/pgsql/ArrayExpressionBuilder.php | 2 +-
 7 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/framework/CHANGELOG.md b/framework/CHANGELOG.md
index 363e48604b..7ebc26b218 100644
--- a/framework/CHANGELOG.md
+++ b/framework/CHANGELOG.md
@@ -67,6 +67,7 @@ Yii Framework 2 Change Log
 - Bug #20617: Fix `@return` annotation for `DataColumn::getDataCellValue()` (mspirkov)
 - Bug #20628: Fix `@return` annotations for `lastInsertId` methods in `yii\db\mssql` namespace (mspirkov)
 - Bug #20630: Fix `@var` annotations for `yii\web\CompositeUrlRule::$rules` and `yii\web\GroupUrlRule::$rules` (mspirkov)
+- Bug #20634: Fix PHPDoc annotations in `yii\db` namespace. Add PHPStan/Psalm annotations for `yii\db\SqlTokenizer::startsWithAnyLongest()` (mspirkov)
 - Bug #20636: Fix `@param` annotations for `$message` in logging methods (mspirkov)
 
 
diff --git a/framework/base/DynamicModel.php b/framework/base/DynamicModel.php
index 219ddc916c..a0f7bbf619 100644
--- a/framework/base/DynamicModel.php
+++ b/framework/base/DynamicModel.php
@@ -223,7 +223,7 @@ class DynamicModel extends Model
      */
     public static function validateData(array $data, $rules = [])
     {
-        /** @var self $model */
+        /** @var static $model */
         $model = new static($data);
         if (!empty($rules)) {
             $validators = $model->getValidators();
diff --git a/framework/db/ActiveRelationTrait.php b/framework/db/ActiveRelationTrait.php
index 53addd17ef..2347098ff7 100644
--- a/framework/db/ActiveRelationTrait.php
+++ b/framework/db/ActiveRelationTrait.php
@@ -45,7 +45,7 @@ trait ActiveRelationTrait
      */
     public $link;
     /**
-     * @var array|object the query associated with the junction table. Please call [[via()]]
+     * @var array|object|null the query associated with the junction table. Please call [[via()]]
      * to set this property instead of directly setting it.
      * This property is only used in relational context.
      * @see via()
diff --git a/framework/db/ColumnSchema.php b/framework/db/ColumnSchema.php
index ef3c9b06d4..4893d528fc 100644
--- a/framework/db/ColumnSchema.php
+++ b/framework/db/ColumnSchema.php
@@ -62,7 +62,7 @@ class ColumnSchema extends BaseObject
      */
     public $scale;
     /**
-     * @var bool whether this column is a primary key
+     * @var bool|null whether this column is a primary key
      */
     public $isPrimaryKey;
     /**
diff --git a/framework/db/QueryBuilder.php b/framework/db/QueryBuilder.php
index a83c2b3a14..476ce3d41a 100644
--- a/framework/db/QueryBuilder.php
+++ b/framework/db/QueryBuilder.php
@@ -319,6 +319,7 @@ class QueryBuilder extends \yii\base\BaseObject
         }
 
         if ($this->expressionBuilders[$className] === __CLASS__) {
+            /** @phpstan-var $this&ExpressionBuilderInterface */
             return $this;
         }
 
diff --git a/framework/db/SqlTokenizer.php b/framework/db/SqlTokenizer.php
index 63e53a9b4d..6cba2f9bfe 100644
--- a/framework/db/SqlTokenizer.php
+++ b/framework/db/SqlTokenizer.php
@@ -176,12 +176,15 @@ abstract class SqlTokenizer extends Component
 
     /**
      * Returns whether the longest common prefix equals to the SQL code of the same length at the current offset.
-     * @param string[] $with strings to be tested.
+     * @param array $with strings to be tested.
      * The method **will** modify this parameter to speed up lookups.
      * @param bool $caseSensitive whether to perform a case sensitive comparison.
      * @param int|null $length length of the matched string.
      * @param string|null $content matched string.
      * @return bool whether a match is found.
+     *
+     * @phpstan-param array<int, string>|array<int, array<string, mixed>> $with
+     * @psalm-param array<int, string>|array<int, array<string, mixed>> $with
      */
     protected function startsWithAnyLongest(array &$with, $caseSensitive, &$length = null, &$content = null)
     {
@@ -194,6 +197,7 @@ abstract class SqlTokenizer extends Component
                 return mb_strlen($string2, 'UTF-8') - mb_strlen($string1, 'UTF-8');
             });
             $map = [];
+            /** @var string $string */
             foreach ($with as $string) {
                 $map[mb_strlen($string, 'UTF-8')][$caseSensitive ? $string : mb_strtoupper($string, 'UTF-8')] = true;
             }
diff --git a/framework/db/pgsql/ArrayExpressionBuilder.php b/framework/db/pgsql/ArrayExpressionBuilder.php
index 9da7f257cc..128a633ed5 100644
--- a/framework/db/pgsql/ArrayExpressionBuilder.php
+++ b/framework/db/pgsql/ArrayExpressionBuilder.php
@@ -132,7 +132,7 @@ class ArrayExpressionBuilder implements ExpressionBuilderInterface
      *
      * @param ArrayExpression $expression
      * @param mixed $value
-     * @return JsonExpression
+     * @return mixed
      */
     protected function typecastValue(ArrayExpression $expression, $value)
     {