Clean code ArrayExpressionBuilder::class. (#246)

terabytesoftw · web-flow · commit 0ae9efd3ff7f · 2023-03-03T19:04:42.000-03:00
diff --git a/src/Builder/ArrayExpressionBuilder.php b/src/Builder/ArrayExpressionBuilder.php
@@ -23,7 +23,7 @@
 use function str_repeat;
 
 /**
- * The class ArrayExpressionBuilder builds {@see ArrayExpression} for PostgresSQL DBMS.
+ * Builds expressions for {@see `Yiisoft\Db\Expression\ArrayExpression`} for PostgresSQL Server.
  */
 final class ArrayExpressionBuilder implements ExpressionBuilderInterface
 {
@@ -32,21 +32,23 @@ public function __construct(private QueryBuilderInterface $queryBuilder)
     }
 
     /**
-     * Method builds the raw SQL from the $expression that will not be additionally escaped or quoted.
+     * 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.
+     * @param ExpressionInterface $expression The expression to be built.
+     * @param array $params The binding parameters.
      *
-     * @throws Exception|InvalidArgumentException|InvalidConfigException|NotSupportedException
+     * @throws Exception
+     * @throws InvalidArgumentException
+     * @throws InvalidConfigException
+     * @throws NotSupportedException
      *
-     * @return string the raw SQL that will not be additionally escaped or quoted.
+     * @return string The raw SQL that will not be additionally escaped or quoted.
+     *
+     * @psalm-param ArrayExpression $expression
      */
     public function build(ExpressionInterface $expression, array &$params = []): string
     {
-        /**
-         *  @var ArrayExpression $expression
-         *  @var array|mixed|QueryInterface $value
-         */
+        /** @psalm-var array|mixed|QueryInterface $value */
         $value = $expression->getValue();
 
         if ($value === null) {
@@ -58,7 +60,7 @@ public function build(ExpressionInterface $expression, array &$params = []): str
             return $this->buildSubqueryArray($sql, $expression);
         }
 
-        /** @psalm-var string[] */
+        /** @psalm-var string[] $placeholders */
         $placeholders = $this->buildPlaceholders($expression, $params);
 
         return 'ARRAY[' . implode(', ', $placeholders) . ']' . $this->getTypehint($expression);
@@ -67,33 +69,35 @@ public function build(ExpressionInterface $expression, array &$params = []): str
     /**
      * Builds placeholders array out of $expression values.
      *
-     * @param array $params the binding parameters.
+     * @param array $params The binding parameters.
+     *
+     * @throws Exception
+     * @throws InvalidArgumentException
+     * @throws InvalidConfigException
+     * @throws NotSupportedException
      *
-     * @throws Exception|InvalidArgumentException|InvalidConfigException|NotSupportedException
+     * @psalm-param ArrayExpression $expression
      */
     protected function buildPlaceholders(ExpressionInterface $expression, array &$params): array
     {
         $placeholders = [];
 
-        /**
-         *  @var ArrayExpression $expression
-         *  @var mixed $value
-         */
+        /** @psalm-var mixed $value */
         $value = $expression->getValue();
 
         if (!is_array($value) && !$value instanceof Traversable) {
             return $placeholders;
         }
 
         if ($expression->getDimension() > 1) {
-            /** @var ExpressionInterface|int $item */
+            /** @psalm-var ExpressionInterface|int $item */
             foreach ($value as $item) {
                 $placeholders[] = $this->build($this->unnestArrayExpression($expression, $item), $params);
             }
             return $placeholders;
         }
 
-        /** @var ExpressionInterface|int $item */
+        /** @psalm-var ExpressionInterface|int $item */
         foreach ($value as $item) {
             if ($item instanceof QueryInterface) {
                 [$sql, $params] = $this->queryBuilder->build($item, $params);
@@ -114,16 +118,13 @@ protected function buildPlaceholders(ExpressionInterface $expression, array &$pa
         return $placeholders;
     }
 
-    /**
-     * @param array|mixed|QueryInterface $value
-     */
     private function unnestArrayExpression(ArrayExpression $expression, mixed $value): ArrayExpression
     {
         return new ArrayExpression($value, $expression->getType(), $expression->getDimension() - 1);
     }
 
     /**
-     * @return string the typecast expression based on {@see type}.
+     * @return string The typecast expression based on {@see type}.
      */
     protected function getTypeHint(ArrayExpression $expression): string
     {
@@ -141,21 +142,20 @@ protected function getTypeHint(ArrayExpression $expression): string
     }
 
     /**
-     * Build an array expression from a subquery SQL.
+     * Build an array expression from a sub-query SQL.
      *
-     * @param string $sql the subquery SQL.
+     * @param string $sql The sub-query SQL.
+     * @param ArrayExpression $expression The array expression.
      *
-     * @return string the subquery array expression.
+     * @return string The sub-query array expression.
      */
     protected function buildSubqueryArray(string $sql, ArrayExpression $expression): string
     {
         return 'ARRAY(' . $sql . ')' . $this->getTypeHint($expression);
     }
 
     /**
-     * Casts $value to use in $expression.
-     *
-     * @return array|bool|ExpressionInterface|int|JsonExpression|string|null
+     * @return array|bool|ExpressionInterface|int|JsonExpression|string|null The cast value or expression.
      */
     protected function typecastValue(
         ArrayExpression $expression,
