Clarify return type of phpTypecast() methods for range columns

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Enh #482: Improve performance of `SqlParser::getNextPlaceholder()` method (@Tigrov)
 - Chg #483: Bump `yiisoft/db` version to `^2.0.1` (@vjik)
 - Bug #484: Fix building range-type column definitions (@Tigrov)
+- Enh #489: Clarify return type of `phpTypecast()` methods for range columns (@Tigrov)
 
 ## 2.0.1 February 07, 2026
 

src/Column/AbstractMultiRangeColumn.php

@@ -14,8 +14,16 @@
 use function is_array;
 use function is_string;
 
+/**
+ * @template T of ExpressionInterface
+ */
 abstract class AbstractMultiRangeColumn extends AbstractColumn
 {
+    /**
+     * @inheritDoc
+     *
+     * @return string|ExpressionInterface|MultiRangeValue|null
+     */
     public function dbTypecast(mixed $value): mixed
     {
         if ($value === null
@@ -42,6 +50,13 @@ public function dbTypecast(mixed $value): mixed
         return new MultiRangeValue(...$ranges);
     }
 
+    /**
+     * @inheritDoc
+     *
+     * @return ?ExpressionInterface[]
+     *
+     * @psalm-return ?T[]
+     */
     public function phpTypecast(mixed $value): mixed
     {
         /**
@@ -64,11 +79,16 @@ public function phpTypecast(mixed $value): mixed
         preg_match_all('/[\[\(][^,]*,[^\)\]]*[\)\]]/', $value, $matches);
 
         $rangeColumn = $this->getRangeColumn();
+
+        /** @psalm-var T[] */
         return array_map(
             $rangeColumn->phpTypecast(...),
             $matches[0],
         );
     }
 
+    /**
+     * @psalm-return AbstractRangeColumn<T>
+     */
     abstract protected function getRangeColumn(): ColumnInterface;
 }

src/Column/AbstractRangeColumn.php

@@ -15,8 +15,16 @@
 use function is_string;
 use function sprintf;
 
+/**
+ * @template T of ExpressionInterface
+ */
 abstract class AbstractRangeColumn extends AbstractColumn
 {
+    /**
+     * @inheritDoc
+     *
+     * @return string|ExpressionInterface|null
+     */
     public function dbTypecast(mixed $value): mixed
     {
         if ($value === null
@@ -45,6 +53,13 @@ public function dbTypecast(mixed $value): mixed
             . ']';
     }
 
+    /**
+     * @inheritDoc
+     *
+     * @return ?ExpressionInterface
+     *
+     * @psalm-return ?T
+     */
     public function phpTypecast(mixed $value): mixed
     {
         /**
@@ -56,7 +71,7 @@ public function phpTypecast(mixed $value): mixed
             return null;
         }
 
-        if (!preg_match('/^(?P<open>\[|\()(?P<lower>[^,]*),(?P<upper>[^\)\]]*)(?P<close>\)|\])$/', $value, $matches)) {
+        if (!preg_match('/^(?P<open>[\[\(])(?P<lower>[^,]*),(?P<upper>[^\)\]]*)(?P<close>[\)\]])$/', $value, $matches)) {
             throw new NotSupportedException('Unsupported range format.');
         }
 
@@ -72,6 +87,8 @@ abstract protected function getBoundColumn(): ColumnInterface;
 
     /**
      * @throws NotSupportedException
+     *
+     * @psalm-return T
      */
     abstract protected function createRangeValue(
         ?string $lower,

src/Column/DateMultiRangeColumn.php

@@ -5,8 +5,12 @@
 namespace Yiisoft\Db\Pgsql\Column;
 
 use Yiisoft\Db\Pgsql\Constant\PgsqlColumnType;
+use Yiisoft\Db\Pgsql\Expression\DateRangeValue;
 use Yiisoft\Db\Schema\Column\ColumnInterface;
 
+/**
+ * @extends AbstractMultiRangeColumn<DateRangeValue>
+ */
 final class DateMultiRangeColumn extends AbstractMultiRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::DATEMULTIRANGE;

src/Column/DateRangeColumn.php

@@ -8,17 +8,29 @@
 use Yiisoft\Db\Pgsql\Expression\DateRangeValue;
 use Yiisoft\Db\Schema\Column\DateTimeColumn;
 
+/**
+ * @extends AbstractRangeColumn<DateRangeValue>
+ */
 final class DateRangeColumn extends AbstractRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::DATERANGE;
 
+    public function phpTypecast(mixed $value): ?DateRangeValue
+    {
+        return parent::phpTypecast($value);
+    }
+
     protected function getBoundColumn(): DateTimeColumn
     {
         return RangeBoundColumnFactory::date();
     }
 
-    protected function createRangeValue(?string $lower, ?string $upper, bool $includeLower, bool $includeUpper): DateRangeValue
-    {
+    protected function createRangeValue(
+        ?string $lower,
+        ?string $upper,
+        bool $includeLower,
+        bool $includeUpper,
+    ): DateRangeValue {
         $column = $this->getBoundColumn();
         return new DateRangeValue(
             $column->phpTypecast($lower),

src/Column/Int4MultiRangeColumn.php

@@ -5,8 +5,12 @@
 namespace Yiisoft\Db\Pgsql\Column;
 
 use Yiisoft\Db\Pgsql\Constant\PgsqlColumnType;
+use Yiisoft\Db\Pgsql\Expression\Int4RangeValue;
 use Yiisoft\Db\Schema\Column\ColumnInterface;
 
+/**
+ * @extends AbstractMultiRangeColumn<Int4RangeValue>
+ */
 final class Int4MultiRangeColumn extends AbstractMultiRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::INT4MULTIRANGE;

src/Column/Int4RangeColumn.php

@@ -7,10 +7,18 @@
 use Yiisoft\Db\Pgsql\Constant\PgsqlColumnType;
 use Yiisoft\Db\Pgsql\Expression\Int4RangeValue;
 
+/**
+ * @extends AbstractRangeColumn<Int4RangeValue>
+ */
 final class Int4RangeColumn extends AbstractRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::INT4RANGE;
 
+    public function phpTypecast(mixed $value): ?Int4RangeValue
+    {
+        return parent::phpTypecast($value);
+    }
+
     protected function getBoundColumn(): IntegerColumn
     {
         return RangeBoundColumnFactory::int4();

src/Column/Int8MultiRangeColumn.php

@@ -5,8 +5,12 @@
 namespace Yiisoft\Db\Pgsql\Column;
 
 use Yiisoft\Db\Pgsql\Constant\PgsqlColumnType;
+use Yiisoft\Db\Pgsql\Expression\Int8RangeValue;
 use Yiisoft\Db\Schema\Column\ColumnInterface;
 
+/**
+ * @extends AbstractMultiRangeColumn<Int8RangeValue>
+ */
 final class Int8MultiRangeColumn extends AbstractMultiRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::INT8MULTIRANGE;

src/Column/Int8RangeColumn.php

@@ -7,10 +7,18 @@
 use Yiisoft\Db\Pgsql\Constant\PgsqlColumnType;
 use Yiisoft\Db\Pgsql\Expression\Int8RangeValue;
 
+/**
+ * @extends AbstractRangeColumn<Int8RangeValue>
+ */
 final class Int8RangeColumn extends AbstractRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::INT8RANGE;
 
+    public function phpTypecast(mixed $value): ?Int8RangeValue
+    {
+        return parent::phpTypecast($value);
+    }
+
     protected function getBoundColumn(): BigIntColumn|IntegerColumn
     {
         return RangeBoundColumnFactory::int8();

src/Column/NumMultiRangeColumn.php

@@ -5,8 +5,12 @@
 namespace Yiisoft\Db\Pgsql\Column;
 
 use Yiisoft\Db\Pgsql\Constant\PgsqlColumnType;
+use Yiisoft\Db\Pgsql\Expression\NumRangeValue;
 use Yiisoft\Db\Schema\Column\ColumnInterface;
 
+/**
+ * @extends AbstractMultiRangeColumn<NumRangeValue>
+ */
 final class NumMultiRangeColumn extends AbstractMultiRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::NUMMULTIRANGE;

src/Column/NumRangeColumn.php

@@ -8,10 +8,18 @@
 use Yiisoft\Db\Pgsql\Expression\NumRangeValue;
 use Yiisoft\Db\Schema\Column\DoubleColumn;
 
+/**
+ * @extends AbstractRangeColumn<NumRangeValue>
+ */
 final class NumRangeColumn extends AbstractRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::NUMRANGE;
 
+    public function phpTypecast(mixed $value): ?NumRangeValue
+    {
+        return parent::phpTypecast($value);
+    }
+
     protected function getBoundColumn(): DoubleColumn
     {
         return RangeBoundColumnFactory::num();

src/Column/TsMultiRangeColumn.php

@@ -5,8 +5,12 @@
 namespace Yiisoft\Db\Pgsql\Column;
 
 use Yiisoft\Db\Pgsql\Constant\PgsqlColumnType;
+use Yiisoft\Db\Pgsql\Expression\TsRangeValue;
 use Yiisoft\Db\Schema\Column\ColumnInterface;
 
+/**
+ * @extends AbstractMultiRangeColumn<TsRangeValue>
+ */
 final class TsMultiRangeColumn extends AbstractMultiRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::TSMULTIRANGE;

src/Column/TsRangeColumn.php

@@ -8,10 +8,18 @@
 use Yiisoft\Db\Pgsql\Expression\TsRangeValue;
 use Yiisoft\Db\Schema\Column\DateTimeColumn;
 
+/**
+ * @extends AbstractRangeColumn<TsRangeValue>
+ */
 final class TsRangeColumn extends AbstractRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::TSRANGE;
 
+    public function phpTypecast(mixed $value): ?TsRangeValue
+    {
+        return parent::phpTypecast($value);
+    }
+
     protected function getBoundColumn(): DateTimeColumn
     {
         return RangeBoundColumnFactory::ts();

src/Column/TsTzMultiRangeColumn.php

@@ -5,8 +5,12 @@
 namespace Yiisoft\Db\Pgsql\Column;
 
 use Yiisoft\Db\Pgsql\Constant\PgsqlColumnType;
+use Yiisoft\Db\Pgsql\Expression\TsTzRangeValue;
 use Yiisoft\Db\Schema\Column\ColumnInterface;
 
+/**
+ * @extends AbstractMultiRangeColumn<TsTzRangeValue>
+ */
 final class TsTzMultiRangeColumn extends AbstractMultiRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::TSTZMULTIRANGE;

src/Column/TsTzRangeColumn.php

@@ -8,10 +8,18 @@
 use Yiisoft\Db\Pgsql\Expression\TsTzRangeValue;
 use Yiisoft\Db\Schema\Column\DateTimeColumn;
 
+/**
+ * @extends AbstractRangeColumn<TsTzRangeValue>
+ */
 final class TsTzRangeColumn extends AbstractRangeColumn
 {
     protected const DEFAULT_TYPE = PgsqlColumnType::TSTZRANGE;
 
+    public function phpTypecast(mixed $value): ?TsTzRangeValue
+    {
+        return parent::phpTypecast($value);
+    }
+
     protected function getBoundColumn(): DateTimeColumn
     {
         return RangeBoundColumnFactory::tsTz();