Add ColumnName and Value expressions. Remove BetweenColumns condition (#1024)

Author: vjik

CHANGELOG.md

@@ -121,11 +121,12 @@
 - Enh #1016: Refactor `AbstractDMLQueryBuilder::getTableUniqueColumnNames()` method (@Tigrov)
 - New #1015: Add mode parameter to `Like` condition (@vjik)
 - Chg #1019: Split `In` condition to `In` and `NotIn` (@vjik)
-- Chg #1018: Split `BetweenColumns` condition to `BetweenColumns` and `NotBetweenColumns` (@vjik)
+- Chg #1018, #1024: Remove `BetweenColumns` in favor `Between` with `ColumnName` usage (@vjik)
 - Chg #1017: Split `Between` condition to `Between` and `NotBetween` (@vjik)
 - New #1020: Support column's collation (@Tigrov)
 - Chg #1021: Move conjunction type from operator string value to `Like` condition constructor parameter (@vjik)
 - Chg #1023: Split `Like` condition to `Like` and `NotLike` (@vjik)
+- New #1024: Add `ColumnName` and `Value` expressions (@vjik)  
 
 ## 1.3.0 March 21, 2024
 

UPGRADE.md

@@ -268,3 +268,4 @@ Each table column has its own class in the `Yiisoft\Db\Schema\Column` namespace
 - Remove `AbstractDsn` and `AbstractDsnSocket` classes and `DsnInterface` interface;
 - Remove `Hash` condition;
 - Remove `AbstractTableSchema` and add `TableSchema` instead;
+- Remove `BetweenColumns` condition;

docs/guide/en/query/where.md

@@ -139,9 +139,17 @@ Operand 1 should be the column name, and operand 2 and 3 should be the starting
 
 For example, `['between', 'id', 1,10]` will generate `id BETWEEN 1 AND 10`.
 
-In case you need to build a condition where value is between two columns `(like 11 BETWEEN min_id AND max_id)`,
+You can also use `Yiisoft\Db\Expression\ColumnName` and `Yiisoft\Db\Expression\Value` expressions:
 
-you should use `Yiisoft\Db\QueryBuilder\Condition\BetweenColumnsCondition`.
+```php
+use Yiisoft\Db\Expression\ColumnName;
+use Yiisoft\Db\Expression\Value;
+
+['between', new Value('2025-08-11'), new ColumnName('start_date'), new ColumnName('end_date')]
+```
+
+The `ColumnName` expression ensures proper quoting of column names, while `Value` expressions ensure proper parameter 
+binding for values.
 
 ### not between
 

docs/guide/pt-BR/query/where.md

@@ -139,10 +139,6 @@ O operando 1 deve ser o nome da coluna e os operandos 2 e 3 devem ser os valores
 
 Por exemplo, `['between', 'id', 1,10]` irá gerar `id BETWEEN 1 AND 10`.
 
-Caso você precise construir uma condição onde o valor esteja entre duas colunas `(like 11 BETWEEN min_id AND max_id)`,
-
-você deve usar `Yiisoft\Db\QueryBuilder\Condition\BetweenColumnsCondition`.
-
 ### not between
 
 Semelhante a `between` exceto que `BETWEEN` é substituído por `NOT BETWEEN` na condição gerada.

src/Expression/ColumnName.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Expression;
+
+/**
+ * Represents a column name expression for SQL queries.
+ *
+ * This class encapsulates a column name that will be properly quoted when building SQL queries.
+ */
+final class ColumnName implements ExpressionInterface
+{
+    /**
+     * @param string $name The column name.
+     */
+    public function __construct(
+        public readonly string $name,
+    ) {
+    }
+}

src/Expression/ColumnNameBuilder.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Expression;
+
+use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
+
+/**
+ * Builder for {@see ColumnName} expressions.
+ *
+ * This builder takes {@see ColumnName} expressions and converts them into properly quoted column names suitable for
+ * inclusion in SQL statements using the database-specific quoting rules.
+ *
+ * @implements ExpressionBuilderInterface<ColumnName>
+ */
+final class ColumnNameBuilder implements ExpressionBuilderInterface
+{
+    /**
+     * @param QueryBuilderInterface $queryBuilder The query builder instance.
+     */
+    public function __construct(
+        private readonly QueryBuilderInterface $queryBuilder,
+    ) {
+    }
+
+    public function build(ExpressionInterface $expression, array &$params = []): string
+    {
+        return $this->queryBuilder->getQuoter()->quoteColumnName($expression->name);
+    }
+}

src/Expression/Value.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Expression;
+
+/**
+ * Represents a value for SQL queries.
+ *
+ * This class encapsulates any type of value that needs to be properly converted and bound as a parameter in SQL
+ * statements.
+ */
+final class Value implements ExpressionInterface
+{
+    /**
+     * @param mixed $value The value to be used in the SQL query.
+     */
+    public function __construct(
+        public readonly mixed $value,
+    ) {
+    }
+}

src/Expression/ValueBuilder.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Expression;
+
+use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
+
+/**
+ * Builder for {@see Value} expressions that converts values into SQL parameters.
+ *
+ * This builder takes {@see Value} expressions and converts them into properly formatted SQL parameter placeholders
+ * while adding the actual values to the parameters array for safe binding during query execution.
+ *
+ * @implements ExpressionBuilderInterface<Value>
+ */
+final class ValueBuilder implements ExpressionBuilderInterface
+{
+    /**
+     * @param QueryBuilderInterface $queryBuilder The query builder instance.
+     */
+    public function __construct(
+        private readonly QueryBuilderInterface $queryBuilder,
+    ) {
+    }
+
+    public function build(ExpressionInterface $expression, array &$params = []): string
+    {
+        return $this->queryBuilder->buildValue($expression->value, $params);
+    }
+}

src/QueryBuilder/AbstractDQLQueryBuilder.php

@@ -12,6 +12,8 @@
 use Yiisoft\Db\Exception\NotSupportedException;
 use Yiisoft\Db\Expression\ArrayExpression;
 use Yiisoft\Db\Expression\ArrayExpressionBuilder;
+use Yiisoft\Db\Expression\ColumnName;
+use Yiisoft\Db\Expression\ColumnNameBuilder;
 use Yiisoft\Db\Expression\Expression;
 use Yiisoft\Db\Expression\ExpressionBuilder;
 use Yiisoft\Db\Expression\ExpressionBuilderInterface;
@@ -22,6 +24,8 @@
 use Yiisoft\Db\Expression\CaseExpressionBuilder;
 use Yiisoft\Db\Expression\StructuredExpression;
 use Yiisoft\Db\Expression\StructuredExpressionBuilder;
+use Yiisoft\Db\Expression\Value;
+use Yiisoft\Db\Expression\ValueBuilder;
 use Yiisoft\Db\QueryBuilder\Condition\ConditionInterface;
 use Yiisoft\Db\QueryBuilder\Condition\Simple;
 use Yiisoft\Db\Query\Query;
@@ -558,12 +562,12 @@ protected function defaultExpressionBuilders(): array
             Condition\Equals::class => Condition\Builder\EqualsBuilder::class,
             Condition\Exists::class => Condition\Builder\ExistsBuilder::class,
             Simple::class => Condition\Builder\SimpleBuilder::class,
-            Condition\BetweenColumns::class => Condition\Builder\BetweenColumnsBuilder::class,
-            Condition\NotBetweenColumns::class => Condition\Builder\BetweenColumnsBuilder::class,
             JsonExpression::class => JsonExpressionBuilder::class,
             ArrayExpression::class => ArrayExpressionBuilder::class,
             StructuredExpression::class => StructuredExpressionBuilder::class,
             CaseExpression::class => CaseExpressionBuilder::class,
+            ColumnName::class => ColumnNameBuilder::class,
+            Value::class => ValueBuilder::class,
         ];
     }