Fix #730: Add ExpressionBuilderInterface::build() (#946)

Co-authored-by: Sergei Predvoditelev <[email protected]>

Author: samdark

CHANGELOG.md

@@ -77,6 +77,7 @@
 - New #939: Add `caseSensitive` option to like condition (@vjik)
 - New #942: Allow PHP backed enums as values (@Tigrov)
 - Enh #943: Add `getCacheKey()` and `getCacheTag()` methods to `AbstractPdoSchema` class (@Tigrov)
+- Enh #730: Add `ExpressionBuilderInterface::build()` (@samdark)
 - Enh #944: Added `setWhere()` as a forced method to overwrite `where()` (@lav45)
 - Enh #925, #951: Add callback to `Query::all()` and `Query::one()` methods (@Tigrov, @vjik)
 - New #954: Add `DbArrayHelper::arrange()` method (@Tigrov)

src/Command/ParamBuilder.php

@@ -11,6 +11,8 @@
 
 /**
  * Implements the {@see ExpressionBuilderInterface} interface, is used to build {@see ParamInterface} objects.
+ *
+ * @implements ExpressionBuilderInterface<ExpressionInterface>
  */
 final class ParamBuilder implements ExpressionBuilderInterface
 {

src/Expression/AbstractArrayExpressionBuilder.php

@@ -12,11 +12,13 @@
 
 /**
  * Abstract expression builder for {@see ArrayExpression}.
+ *
+ * @implements ExpressionBuilderInterface<ArrayExpression>
  */
 abstract class AbstractArrayExpressionBuilder implements ExpressionBuilderInterface
 {
     /**
-     * Builds a SQL expression for a string value.
+     * Builds an SQL expression for a string value.
      *
      * @param string $value The valid SQL string representation of the array value.
      * @param ArrayExpression $expression The array expression.

src/Expression/AbstractStructuredExpressionBuilder.php

@@ -20,11 +20,13 @@
 
 /**
  * Abstract expression builder for {@see StructuredExpression}.
+ *
+ * @implements ExpressionBuilderInterface<StructuredExpression>
  */
 abstract class AbstractStructuredExpressionBuilder implements ExpressionBuilderInterface
 {
     /**
-     * Builds a SQL expression for a string value.
+     * Builds an SQL expression for a string value.
      *
      * @param string $value The valid SQL string representation of the structured value.
      * @param StructuredExpression $expression The structured expression.
@@ -54,7 +56,7 @@ abstract protected function buildSubquery(
     ): string;
 
     /**
-     * Builds a SQL expression for a structured value.
+     * Builds an SQL expression for a structured value.
      *
      * @param array|object $value The structured value.
      * @param StructuredExpression $expression The structured expression.

src/Expression/CaseExpressionBuilder.php

@@ -13,6 +13,8 @@
 
 /**
  * Builds expressions for {@see CaseExpression}.
+ *
+ * @implements ExpressionBuilderInterface<CaseExpression>
  */
 class CaseExpressionBuilder implements ExpressionBuilderInterface
 {

src/Expression/Expression.php

@@ -31,7 +31,7 @@ final class Expression implements ExpressionInterface, Stringable
     /**
      * @psalm-param ParamsType $params
      */
-    public function __construct(private string $expression, private array $params = [])
+    public function __construct(private readonly string $expression, private readonly array $params = [])
     {
     }
 

src/Expression/ExpressionBuilder.php

@@ -20,6 +20,8 @@
  * These expressions can be used with the query builder to build complex and customizable database queries
  * {@see Expression} class.
  *
+ * @implements ExpressionBuilderInterface<Expression>
+ *
  * @psalm-import-type ParamsType from ConnectionInterface
  */
 final class ExpressionBuilder implements ExpressionBuilderInterface

src/Expression/ExpressionBuilderInterface.php

@@ -15,7 +15,21 @@
  * database queries, without having to worry about the specific syntax of the underlying database.
  *
  * @see ExpressionInterface
+ *
+ * @template T as ExpressionInterface
  */
 interface ExpressionBuilderInterface
 {
+    /**
+     * Method builds the raw SQL from the expression that will not be additionally
+     * escaped or quoted.
+     *
+     * @param ExpressionInterface $expression The expression to be built.
+     * @param array $params The binding parameters.
+     * @throws \InvalidArgumentException If builder can't handle expression passed.
+     * @return string The raw SQL that will not be additionally escaped or quoted.
+     *
+     * @psalm-param T $expression
+     */
+    public function build(ExpressionInterface $expression, array &$params = []): string;
 }

src/Expression/JsonExpressionBuilder.php

@@ -28,6 +28,8 @@
 
 /**
  * Builds expressions for {@see JsonExpression}.
+ *
+ * @implements ExpressionBuilderInterface<JsonExpression>
  */
 final class JsonExpressionBuilder implements ExpressionBuilderInterface
 {

src/Query/QueryExpressionBuilder.php

@@ -9,11 +9,14 @@
 use Yiisoft\Db\Exception\InvalidConfigException;
 use Yiisoft\Db\Exception\NotSupportedException;
 use Yiisoft\Db\Expression\ExpressionBuilderInterface;
+use Yiisoft\Db\Expression\ExpressionInterface;
 use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
 
 /**
- * Used internally to build {@see Query} object using unified {@see \Yiisoft\Db\QueryBuilder\AbstractQueryBuilder}
+ * Used internally to build a {@see Query} object using unified {@see \Yiisoft\Db\QueryBuilder\AbstractQueryBuilder}
  * expression building interface.
+ *
+ * @implements ExpressionBuilderInterface<QueryInterface>
  */
 final class QueryExpressionBuilder implements ExpressionBuilderInterface
 {
@@ -22,12 +25,14 @@ public function __construct(private QueryBuilderInterface $queryBuilder)
     }
 
     /**
+     * @param QueryInterface $expression
+     *
      * @throws Exception
      * @throws InvalidArgumentException
      * @throws InvalidConfigException
      * @throws NotSupportedException
      */
-    public function build(QueryInterface $expression, array &$params = []): string
+    public function build(ExpressionInterface $expression, array &$params = []): string
     {
         [$sql, $params] = $this->queryBuilder->build($expression, $params);
         return "($sql)";