Rename ArrayExpression, JsonExpression, StructuredExpression

CHANGELOG.md

@@ -144,6 +144,8 @@
 - Enh #1049: Refactor `AbstractDQLQueryBuilder::buildSelect()` to fix possible bugs (@Tigrov)
 - Enh #1051: Refactor `Quoter` class (@Tigrov)
 - Chg #1052: Rearrange expression namespaces (@Tigrov)
+- Chg #1054: Rename `ArrayExpression` to `ArrayValue`, `JsonExpression` to `JsonValue`,
+  `StructuredExpression` to `StructuredValue` (@Tigrov)
 
 ## 1.3.0 March 21, 2024
 

UPGRADE.md

@@ -272,4 +272,11 @@ Each table column has its own class in the `Yiisoft\Db\Schema\Column` namespace
 - Remove `BetweenColumns` condition;
 - Change `QueryBuilderInterface::getExpressionBuilder()` result type to `ExpressionBuilderInterface`;
 - Change `DQLQueryBuilderInterface::getExpressionBuilder()` result type to `ExpressionBuilderInterface`;
+- Rename `ArrayExpression` to `ArrayValue` and move it to `Yiisoft\Db\Expression\Value` namespace;
+- Rename `ArrayExpressionBuilder` to `ArrayValueBuilder` and move it to `Yiisoft\Db\Expression\Value\Builder` namespace;
+- Rename `JsonExpression` to `JsonValue` and move it to `Yiisoft\Db\Expression\Value` namespace;
+- Rename `JsonExpressionBuilder` to `JsonValueBuilder` and move it to `Yiisoft\Db\Expression\Value\Builder` namespace;
+- Rename `StructuredExpression` to `StructuredValue` and move it to `Yiisoft\Db\Expression\Value` namespace;`
+- Rename `StructuredExpressionBuilder` to `StructuredValueBuilder` and move it to `Yiisoft\Db\Expression\Value\Builder`
+  namespace;
 

docs/guide/en/schema/typecasting.md

@@ -322,10 +322,10 @@ final class MyStructuredColumn extends AbstractStructuredColumn
         }
 
         if ($this->getDbType() === 'file_with_name' && $value instanceof FileWithName) {
-            return new StructuredExpression([$value->getPath(), $value->getName()], $this);
+            return new StructuredValue([$value->getPath(), $value->getName()], $this);
         }
 
-        return new StructuredExpression($value, $this);
+        return new StructuredValue($value, $this);
     }
 
     /**

src/Expression/Value/ArrayExpression.php → src/Expression/Value/ArrayValue.php

@@ -18,13 +18,13 @@
  * Expressions of this type can be used in conditions as well:
  *
  * ```php
- * $query->andWhere(['@>', 'items', new ArrayExpression([1, 2, 3], 'integer[]')]);
+ * $query->andWhere(['@>', 'items', new ArrayValue([1, 2, 3], 'integer[]')]);
  * ```
  *
  * Which, depending on DBMS, will result in a well-prepared condition. For example, in PostgresSQL it will be compiled
  * to `WHERE "items" @> ARRAY[1, 2, 3]::integer[]`.
  */
-final class ArrayExpression implements ExpressionInterface
+final class ArrayValue implements ExpressionInterface
 {
     /**
      * @param iterable|LazyArrayInterface|QueryInterface|string|null $value The array value which can be represented as
@@ -48,36 +48,8 @@ final class ArrayExpression implements ExpressionInterface
      * {@see ColumnInterface}.
      */
     public function __construct(
-        private readonly iterable|LazyArrayInterface|QueryInterface|string|null $value,
-        private readonly ColumnInterface|string|null $type = null,
+        public readonly iterable|LazyArrayInterface|QueryInterface|string|null $value,
+        public readonly ColumnInterface|string|null $type = null,
     ) {
     }
-
-    /**
-     * The array column type which can be represented as
-     * - a native database column type;
-     * - an {@see ColumnType abstract} type;
-     * - an instance of {@see ColumnInterface};
-     * - `null` if the type isn't explicitly specified.
-     *
-     * The column type is used to typecast array values before saving into the database and for adding type hint to
-     * the SQL statement. If the type isn't specified and DBMS can't guess it from the context, SQL error will be raised.
-     */
-    public function getType(): ColumnInterface|string|null
-    {
-        return $this->type;
-    }
-
-    /**
-     * The array value which can be represented as
-     * - an `array` of values;
-     * - an instance of {@see Traversable} or {@see LazyArrayInterface} that represents an array of values;
-     * - an instance of {@see QueryInterface} that represents an SQL sub-query;
-     * - a `string` retrieved value from the database that can be parsed into an array;
-     * - `null`.
-     */
-    public function getValue(): iterable|LazyArrayInterface|QueryInterface|string|null
-    {
-        return $this->value;
-    }
 }

src/Expression/Value/Builder/AbstractArrayExpressionBuilder.php → src/Expression/Value/Builder/AbstractArrayValueBuilder.php

@@ -5,7 +5,7 @@
 namespace Yiisoft\Db\Expression\Value\Builder;
 
 use Yiisoft\Db\Expression\ExpressionBuilderInterface;
-use Yiisoft\Db\Expression\Value\ArrayExpression;
+use Yiisoft\Db\Expression\Value\ArrayValue;
 use Yiisoft\Db\Expression\ExpressionInterface;
 use Yiisoft\Db\Query\QueryInterface;
 use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
@@ -14,48 +14,48 @@
 use function is_string;
 
 /**
- * Abstract expression builder for {@see ArrayExpression}.
+ * Abstract expression builder for {@see ArrayValue}.
  *
- * @implements ExpressionBuilderInterface<ArrayExpression>
+ * @implements ExpressionBuilderInterface<ArrayValue>
  */
-abstract class AbstractArrayExpressionBuilder implements ExpressionBuilderInterface
+abstract class AbstractArrayValueBuilder implements ExpressionBuilderInterface
 {
     /**
      * 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.
+     * @param ArrayValue $expression The array expression.
      * @param array $params The binding parameters.
      *
      * @return string The SQL expression representing the array value.
      */
-    abstract protected function buildStringValue(string $value, ArrayExpression $expression, array &$params): string;
+    abstract protected function buildStringValue(string $value, ArrayValue $expression, array &$params): string;
 
     /**
      * Build an array expression from a sub-query object.
      *
      * @param QueryInterface $query The sub-query object.
-     * @param ArrayExpression $expression The array expression.
+     * @param ArrayValue $expression The array expression.
      * @param array $params The binding parameters.
      *
      * @return string The sub-query SQL expression representing an array.
      */
     abstract protected function buildSubquery(
         QueryInterface $query,
-        ArrayExpression $expression,
+        ArrayValue $expression,
         array &$params
     ): string;
 
     /**
      * Builds a SQL expression for an array value.
      *
      * @param iterable $value The array value.
-     * @param ArrayExpression $expression The array expression.
+     * @param ArrayValue $expression The array expression.
      * @param array $params The binding parameters.
      *
      * @return string The SQL expression representing the array value.
      */
-    abstract protected function buildValue(iterable $value, ArrayExpression $expression, array &$params): string;
+    abstract protected function buildValue(iterable $value, ArrayValue $expression, array &$params): string;
 
     /**
      * Returns the value of the lazy array as an array or a raw string depending on the implementation.
@@ -73,14 +73,14 @@ public function __construct(protected readonly QueryBuilderInterface $queryBuild
     /**
      * The Method builds the raw SQL from the `$expression` that won't be additionally escaped or quoted.
      *
-     * @param ArrayExpression $expression The expression to build.
+     * @param ArrayValue $expression The expression to build.
      * @param array $params The binding parameters.
      *
      * @return string The raw SQL that won't be additionally escaped or quoted.
      */
     public function build(ExpressionInterface $expression, array &$params = []): string
     {
-        $value = $expression->getValue();
+        $value = $expression->value;
 
         if ($value === null) {
             return 'NULL';

src/Expression/Value/Builder/AbstractStructuredExpressionBuilder.php → src/Expression/Value/Builder/AbstractStructuredValueBuilder.php

@@ -4,13 +4,9 @@
 
 namespace Yiisoft\Db\Expression\Value\Builder;
 
-use Yiisoft\Db\Exception\Exception;
-use InvalidArgumentException;
-use Yiisoft\Db\Exception\InvalidConfigException;
-use Yiisoft\Db\Exception\NotSupportedException;
 use Yiisoft\Db\Expression\ExpressionBuilderInterface;
 use Yiisoft\Db\Expression\ExpressionInterface;
-use Yiisoft\Db\Expression\Value\StructuredExpression;
+use Yiisoft\Db\Expression\Value\StructuredValue;
 use Yiisoft\Db\Helper\DbArrayHelper;
 use Yiisoft\Db\Query\QueryInterface;
 use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
@@ -22,54 +18,54 @@
 use function is_string;
 
 /**
- * Abstract expression builder for {@see StructuredExpression}.
+ * Abstract expression builder for {@see StructuredValue}.
  *
- * @implements ExpressionBuilderInterface<StructuredExpression>
+ * @implements ExpressionBuilderInterface<StructuredValue>
  */
-abstract class AbstractStructuredExpressionBuilder implements ExpressionBuilderInterface
+abstract class AbstractStructuredValueBuilder implements ExpressionBuilderInterface
 {
     /**
      * 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.
+     * @param StructuredValue $expression The structured expression.
      * @param array $params The binding parameters.
      *
      * @return string The SQL expression representing the structured value.
      */
     abstract protected function buildStringValue(
         string $value,
-        StructuredExpression $expression,
+        StructuredValue $expression,
         array &$params
     ): string;
 
     /**
      * Build a structured expression from a sub-query object.
      *
      * @param QueryInterface $query The sub-query object.
-     * @param StructuredExpression $expression The structured expression.
+     * @param StructuredValue $expression The structured expression.
      * @param array $params The binding parameters.
      *
      * @return string The sub-query SQL expression representing a structured value.
      */
     abstract protected function buildSubquery(
         QueryInterface $query,
-        StructuredExpression $expression,
+        StructuredValue $expression,
         array &$params
     ): string;
 
     /**
      * Builds an SQL expression for a structured value.
      *
      * @param array|object $value The structured value.
-     * @param StructuredExpression $expression The structured expression.
+     * @param StructuredValue $expression The structured expression.
      * @param array $params The binding parameters.
      *
      * @return string The SQL expression representing the structured value.
      */
     abstract protected function buildValue(
         array|object $value,
-        StructuredExpression $expression,
+        StructuredValue $expression,
         array &$params
     ): string;
 
@@ -89,19 +85,14 @@ public function __construct(protected readonly QueryBuilderInterface $queryBuild
     /**
      * The method builds the raw SQL from the `$expression` that won't be additionally escaped or quoted.
      *
-     * @param StructuredExpression $expression The expression to build.
+     * @param StructuredValue $expression The expression to build.
      * @param array $params The binding parameters.
      *
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @throws InvalidConfigException
-     * @throws NotSupportedException
-     *
      * @return string The raw SQL that won't be additionally escaped or quoted.
      */
     public function build(ExpressionInterface $expression, array &$params = []): string
     {
-        $value = $expression->getValue();
+        $value = $expression->value;
 
         if ($value === null) {
             return 'NULL';
@@ -133,13 +124,13 @@ public function build(ExpressionInterface $expression, array &$params = []): str
      * If the structured type columns are not specified it will only convert the object to an array.
      *
      * @param array|object $value The structured type value.
-     * @param StructuredExpression $expression The structured expression.
+     * @param StructuredValue $expression The structured expression.
      */
-    protected function prepareValues(array|object $value, StructuredExpression $expression): array
+    protected function prepareValues(array|object $value, StructuredValue $expression): array
     {
         $value = DbArrayHelper::toArray($value);
 
-        $type = $expression->getType();
+        $type = $expression->type;
         $columns = $type instanceof AbstractStructuredColumn ? $type->getColumns() : [];
 
         if (empty($columns)) {

src/Expression/Value/Builder/ArrayExpressionBuilder.php → src/Expression/Value/Builder/ArrayValueBuilder.php

@@ -6,7 +6,7 @@
 
 use Yiisoft\Db\Expression\Value\Param;
 use Yiisoft\Db\Constant\DataType;
-use Yiisoft\Db\Expression\Value\ArrayExpression;
+use Yiisoft\Db\Expression\Value\ArrayValue;
 use Yiisoft\Db\Query\QueryInterface;
 use Yiisoft\Db\Schema\Data\JsonLazyArray;
 use Yiisoft\Db\Schema\Data\LazyArray;
@@ -20,25 +20,25 @@
 use const JSON_THROW_ON_ERROR;
 
 /**
- * Default expression builder for {@see ArrayExpression}. Builds an expression as a JSON.
+ * Default expression builder for {@see ArrayValue}. Builds an expression as a JSON.
  */
-final class ArrayExpressionBuilder extends AbstractArrayExpressionBuilder
+final class ArrayValueBuilder extends AbstractArrayValueBuilder
 {
-    protected function buildStringValue(string $value, ArrayExpression $expression, array &$params): string
+    protected function buildStringValue(string $value, ArrayValue $expression, array &$params): string
     {
         $param = new Param($value, DataType::STRING);
 
         return $this->queryBuilder->bindParam($param, $params);
     }
 
-    protected function buildSubquery(QueryInterface $query, ArrayExpression $expression, array &$params): string
+    protected function buildSubquery(QueryInterface $query, ArrayValue $expression, array &$params): string
     {
         [$sql, $params] = $this->queryBuilder->build($query, $params);
 
         return "($sql)";
     }
 
-    protected function buildValue(iterable $value, ArrayExpression $expression, array &$params): string
+    protected function buildValue(iterable $value, ArrayValue $expression, array &$params): string
     {
         if (!is_array($value)) {
             $value = iterator_to_array($value, false);

src/Expression/Value/Builder/JsonExpressionBuilder.php → src/Expression/Value/Builder/JsonValueBuilder.php

@@ -4,18 +4,13 @@
 
 namespace Yiisoft\Db\Expression\Value\Builder;
 
-use JsonException;
 use JsonSerializable;
 use Traversable;
 use Yiisoft\Db\Expression\ExpressionBuilderInterface;
 use Yiisoft\Db\Expression\Value\Param;
 use Yiisoft\Db\Constant\DataType;
-use Yiisoft\Db\Exception\Exception;
-use InvalidArgumentException;
-use Yiisoft\Db\Exception\InvalidConfigException;
-use Yiisoft\Db\Exception\NotSupportedException;
 use Yiisoft\Db\Expression\ExpressionInterface;
-use Yiisoft\Db\Expression\Value\JsonExpression;
+use Yiisoft\Db\Expression\Value\JsonValue;
 use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
 use Yiisoft\Db\Schema\Data\JsonLazyArray;
 use Yiisoft\Db\Schema\Data\LazyArray;
@@ -30,11 +25,11 @@
 use const JSON_THROW_ON_ERROR;
 
 /**
- * Builds expressions for {@see JsonExpression}.
+ * Builds expressions for {@see JsonValue}.
  *
- * @implements ExpressionBuilderInterface<JsonExpression>
+ * @implements ExpressionBuilderInterface<JsonValue>
  */
-final class JsonExpressionBuilder implements ExpressionBuilderInterface
+final class JsonValueBuilder implements ExpressionBuilderInterface
 {
     public function __construct(private readonly QueryBuilderInterface $queryBuilder)
     {
@@ -43,20 +38,14 @@ public function __construct(private readonly QueryBuilderInterface $queryBuilder
     /**
      * The method builds the raw SQL from the `$expression` that won't be additionally escaped or quoted.
      *
-     * @param JsonExpression $expression The expression to build.
+     * @param JsonValue $expression The expression to build.
      * @param array $params The binding parameters.
      *
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @throws InvalidConfigException
-     * @throws JsonException
-     * @throws NotSupportedException
-     *
      * @return string The raw SQL that won't be additionally escaped or quoted.
      */
     public function build(ExpressionInterface $expression, array &$params = []): string
     {
-        $value = $expression->getValue();
+        $value = $expression->value;
 
         if ($value === null) {
             return 'NULL';