Merge pull request #633 from nextras/collection-functions-refactorings

Collection functions refactorings

src/Collection/Aggregations/AnyAggregator.php

@@ -61,7 +61,7 @@ public function aggregateExpression(
 			toExpression: $join->toExpression,
 			toArgs: $join->toArgs,
 			toAlias: $join->toAlias,
-			onExpression:  "($join->onExpression) AND $expression->expression",
+			onExpression: "($join->onExpression) AND $expression->expression",
 			onArgs: array_merge($join->onArgs, $expression->args),
 			conventions: $join->conventions,
 		);

src/Collection/DbalCollection.php

@@ -134,13 +134,13 @@ public function orderBy($expression, string $direction = ICollection::ASC): ICol
 
 			foreach ($expression as $subExpression => $subDirection) {
 				$collection->ordering[] = [
-					$helper->processPropertyExpr($collection->queryBuilder, $subExpression),
+					$helper->processExpression($collection->queryBuilder, $subExpression, null),
 					$subDirection,
 				];
 			}
 		} else {
 			$collection->ordering[] = [
-				$helper->processPropertyExpr($collection->queryBuilder, $expression),
+				$helper->processExpression($collection->queryBuilder, $expression, null),
 				$direction,
 			];
 		}
@@ -322,10 +322,10 @@ public function getQueryBuilder(): QueryBuilder
 
 		if (count($args) > 0) {
 			array_unshift($args, ICollection::AND);
-			$expression = $helper->processFilterFunction(
+			$expression = $helper->processExpression(
 				$this->queryBuilder,
 				$args,
-				null
+				null,
 			);
 			$joins = $expression->joins;
 			if ($expression->isHavingClause) {
@@ -355,7 +355,7 @@ public function getQueryBuilder(): QueryBuilder
 		if (count($groupBy) > 0) {
 			$this->queryBuilder->groupBy(
 				'%ex' . str_repeat(', %ex', count($groupBy) - 1),
-				...$groupBy
+				...$groupBy,
 			);
 		}
 
@@ -405,7 +405,7 @@ protected function getHelper(): DbalQueryBuilderHelper
 	{
 		if ($this->helper === null) {
 			$repository = $this->mapper->getRepository();
-			$this->helper = new DbalQueryBuilderHelper($repository->getModel(), $repository, $this->mapper);
+			$this->helper = new DbalQueryBuilderHelper($repository);
 		}
 
 		return $this->helper;

src/Collection/Functions/AvgAggregateFunction.php

@@ -20,7 +20,7 @@ public function __construct()
 					return array_sum($values) / $count;
 				},
 				dbalAggregationFunction: 'AVG',
-			)
+			),
 		);
 	}
 }

src/Collection/Functions/BaseCompareFunction.php

@@ -15,13 +15,13 @@
 use function count;
 
 
-abstract class BaseCompareFunction implements IArrayFunction, IQueryBuilderFunction
+abstract class BaseCompareFunction implements CollectionFunction
 {
 	public function processArrayExpression(
 		ArrayCollectionHelper $helper,
 		IEntity $entity,
 		array $args,
-		?IArrayAggregator $aggregator = null
+		?IArrayAggregator $aggregator = null,
 	): ArrayExpressionResult
 	{
 		assert(count($args) === 2);
@@ -38,33 +38,33 @@ public function processArrayExpression(
 				function ($value) use ($targetValue): bool {
 					return $this->evaluateInPhp($value, $targetValue);
 				},
-				$valueReference->value
+				$valueReference->value,
 			);
 			return new ArrayExpressionResult(
-				$values,
-				$valueReference->aggregator,
-				null
+				value: $values,
+				aggregator: $valueReference->aggregator,
+				propertyMetadata: null,
 			);
 		} else {
 			return new ArrayExpressionResult(
-				$this->evaluateInPhp($valueReference->value, $targetValue),
-				null,
-				null
+				value: $this->evaluateInPhp($valueReference->value, $targetValue),
+				aggregator: null,
+				propertyMetadata: null,
 			);
 		}
 	}
 
 
-	public function processQueryBuilderExpression(
+	public function processDbalExpression(
 		DbalQueryBuilderHelper $helper,
 		QueryBuilder $builder,
 		array $args,
-		?IDbalAggregator $aggregator = null
+		?IDbalAggregator $aggregator = null,
 	): DbalExpressionResult
 	{
 		assert(count($args) === 2);
 
-		$expression = $helper->processPropertyExpr($builder, $args[0], $aggregator);
+		$expression = $helper->processExpression($builder, $args[0], $aggregator);
 
 		if ($expression->valueNormalizer !== null) {
 			$cb = $expression->valueNormalizer;
@@ -77,20 +77,15 @@ public function processQueryBuilderExpression(
 	}
 
 
-	/**
-	 * @param mixed $sourceValue
-	 * @param mixed $targetValue
-	 */
-	abstract protected function evaluateInPhp($sourceValue, $targetValue): bool;
+	abstract protected function evaluateInPhp(mixed $sourceValue, mixed $targetValue): bool;
 
 
 	/**
-	 * @param mixed $value
 	 * @phpstan-param literal-string $modifier
 	 */
 	abstract protected function evaluateInDb(
 		DbalExpressionResult $expression,
-		$value,
-		string $modifier
+		mixed $value,
+		string $modifier,
 	): DbalExpressionResult;
 }

src/Collection/Functions/BaseNumericAggregateFunction.php

@@ -20,7 +20,7 @@
 use function is_string;
 
 
-abstract class BaseNumericAggregateFunction implements IArrayFunction, IQueryBuilderFunction
+abstract class BaseNumericAggregateFunction implements CollectionFunction
 {
 	protected function __construct(
 		private readonly NumericAggregator $aggregator,
@@ -33,7 +33,7 @@ public function processArrayExpression(
 		ArrayCollectionHelper $helper,
 		IEntity $entity,
 		array $args,
-		?IArrayAggregator $aggregator = null
+		?IArrayAggregator $aggregator = null,
 	): ArrayExpressionResult
 	{
 		assert(count($args) === 1 && is_string($args[0]));
@@ -50,11 +50,11 @@ public function processArrayExpression(
 	}
 
 
-	public function processQueryBuilderExpression(
+	public function processDbalExpression(
 		DbalQueryBuilderHelper $helper,
 		QueryBuilder $builder,
 		array $args,
-		?IDbalAggregator $aggregator = null
+		?IDbalAggregator $aggregator = null,
 	): DbalExpressionResult
 	{
 		assert(count($args) === 1 && is_string($args[0]));
@@ -63,6 +63,6 @@ public function processQueryBuilderExpression(
 			throw new InvalidStateException("Cannot apply two aggregations simultaneously.");
 		}
 
-		return $helper->processPropertyExpr($builder, $args[0], $this->aggregator)->applyAggregator($builder);
+		return $helper->processExpression($builder, $args[0], $this->aggregator)->applyAggregator($builder);
 	}
 }

src/Collection/Functions/CollectionFunction.php

@@ -0,0 +1,50 @@
+<?php declare(strict_types = 1);
+
+namespace Nextras\Orm\Collection\Functions;
+
+
+use Nextras\Dbal\QueryBuilder\QueryBuilder;
+use Nextras\Orm\Collection\Aggregations\IArrayAggregator;
+use Nextras\Orm\Collection\Aggregations\IDbalAggregator;
+use Nextras\Orm\Collection\Functions\Result\ArrayExpressionResult;
+use Nextras\Orm\Collection\Functions\Result\DbalExpressionResult;
+use Nextras\Orm\Collection\Helpers\ArrayCollectionHelper;
+use Nextras\Orm\Collection\Helpers\DbalQueryBuilderHelper;
+use Nextras\Orm\Entity\IEntity;
+
+
+/**
+ * Collection function for custom functionality over array & dbal storage.
+ * It processes an expression and reuse nested result for further evaluation.
+ * If the collection function does not support particular storage (array or dbal), it may
+ * throw an "unsupported" exception.
+ */
+interface CollectionFunction
+{
+	/**
+	 * Returns a value depending on values of entity; the expression passed by args is evaluated during this method
+	 * execution.
+	 * Usually returns a boolean for filtering evaluation.
+	 * @phpstan-param array<mixed> $args
+	 * @phpstan-param IArrayAggregator<mixed>|null $aggregator
+	 */
+	public function processArrayExpression(
+		ArrayCollectionHelper $helper,
+		IEntity $entity,
+		array $args,
+		?IArrayAggregator $aggregator = null,
+	): ArrayExpressionResult;
+
+
+	/**
+	 * Returns true if entity should stay in the result collection; the condition is evaluated in database and this
+	 * method just returns appropriate Nextras Dbal's filtering expression for passed args.
+	 * @phpstan-param array<int|string, mixed> $args
+	 */
+	public function processDbalExpression(
+		DbalQueryBuilderHelper $helper,
+		QueryBuilder $builder,
+		array $args,
+		?IDbalAggregator $aggregator = null,
+	): DbalExpressionResult;
+}

src/Collection/Functions/CompareEqualsFunction.php

@@ -15,7 +15,7 @@
 
 class CompareEqualsFunction extends BaseCompareFunction
 {
-	protected function evaluateInPhp($sourceValue, $targetValue): bool
+	protected function evaluateInPhp(mixed $sourceValue, mixed $targetValue): bool
 	{
 		if (is_array($targetValue)) {
 			return in_array($sourceValue, $targetValue, true);
@@ -25,7 +25,11 @@ protected function evaluateInPhp($sourceValue, $targetValue): bool
 	}
 
 
-	protected function evaluateInDb(DbalExpressionResult $expression, $value, string $modifier): DbalExpressionResult
+	protected function evaluateInDb(
+		DbalExpressionResult $expression,
+		mixed $value,
+		string $modifier,
+	): DbalExpressionResult
 	{
 		if (is_array($value)) {
 			if (count($value) > 0) {

src/Collection/Functions/CompareGreaterThanEqualsFunction.php

@@ -8,13 +8,17 @@
 
 class CompareGreaterThanEqualsFunction extends BaseCompareFunction
 {
-	protected function evaluateInPhp($sourceValue, $targetValue): bool
+	protected function evaluateInPhp(mixed $sourceValue, mixed $targetValue): bool
 	{
 		return $sourceValue >= $targetValue;
 	}
 
 
-	protected function evaluateInDb(DbalExpressionResult $expression, $value, string $modifier): DbalExpressionResult
+	protected function evaluateInDb(
+		DbalExpressionResult $expression,
+		mixed $value,
+		string $modifier,
+	): DbalExpressionResult
 	{
 		return $expression->append(">= $modifier", $value);
 	}

src/Collection/Functions/CompareGreaterThanFunction.php

@@ -8,13 +8,17 @@
 
 class CompareGreaterThanFunction extends BaseCompareFunction
 {
-	protected function evaluateInPhp($sourceValue, $targetValue): bool
+	protected function evaluateInPhp(mixed $sourceValue, mixed $targetValue): bool
 	{
 		return $sourceValue > $targetValue;
 	}
 
 
-	protected function evaluateInDb(DbalExpressionResult $expression, $value, string $modifier): DbalExpressionResult
+	protected function evaluateInDb(
+		DbalExpressionResult $expression,
+		mixed $value,
+		string $modifier,
+	): DbalExpressionResult
 	{
 		return $expression->append("> $modifier", $value);
 	}

src/Collection/Functions/CompareLikeFunction.php

@@ -18,13 +18,13 @@
 use function str_replace;
 
 
-class CompareLikeFunction implements IArrayFunction, IQueryBuilderFunction
+class CompareLikeFunction implements CollectionFunction
 {
 	public function processArrayExpression(
 		ArrayCollectionHelper $helper,
 		IEntity $entity,
 		array $args,
-		?IArrayAggregator $aggregator = null
+		?IArrayAggregator $aggregator = null,
 	): ArrayExpressionResult
 	{
 		assert(count($args) === 2);
@@ -46,7 +46,7 @@ public function processArrayExpression(
 				function ($value) use ($mode, $targetValue): bool {
 					return $this->evaluateInPhp($mode, $value, $targetValue);
 				},
-				$valueReference->value
+				$valueReference->value,
 			);
 			return new ArrayExpressionResult(
 				value: $values,
@@ -60,16 +60,16 @@ function ($value) use ($mode, $targetValue): bool {
 	}
 
 
-	public function processQueryBuilderExpression(
+	public function processDbalExpression(
 		DbalQueryBuilderHelper $helper,
 		QueryBuilder $builder,
 		array $args,
-		?IDbalAggregator $aggregator = null
+		?IDbalAggregator $aggregator = null,
 	): DbalExpressionResult
 	{
 		assert(count($args) === 2);
 
-		$expression = $helper->processPropertyExpr($builder, $args[0], $aggregator);
+		$expression = $helper->processExpression($builder, $args[0], $aggregator);
 
 		$likeExpression = $args[1];
 		assert($likeExpression instanceof LikeExpression);

src/Collection/Functions/CompareNotEqualsFunction.php

@@ -15,7 +15,7 @@
 
 class CompareNotEqualsFunction extends BaseCompareFunction
 {
-	protected function evaluateInPhp($sourceValue, $targetValue): bool
+	protected function evaluateInPhp(mixed $sourceValue, mixed $targetValue): bool
 	{
 		if (is_array($targetValue)) {
 			return !in_array($sourceValue, $targetValue, true);
@@ -25,7 +25,11 @@ protected function evaluateInPhp($sourceValue, $targetValue): bool
 	}
 
 
-	protected function evaluateInDb(DbalExpressionResult $expression, $value, string $modifier): DbalExpressionResult
+	protected function evaluateInDb(
+		DbalExpressionResult $expression,
+		mixed $value,
+		string $modifier,
+	): DbalExpressionResult
 	{
 		if (is_array($value)) {
 			if (count($value) > 0) {

src/Collection/Functions/CompareSmallerThanEqualsFunction.php

@@ -8,13 +8,17 @@
 
 class CompareSmallerThanEqualsFunction extends BaseCompareFunction
 {
-	protected function evaluateInPhp($sourceValue, $targetValue): bool
+	protected function evaluateInPhp(mixed $sourceValue, mixed $targetValue): bool
 	{
 		return $sourceValue <= $targetValue;
 	}
 
 
-	protected function evaluateInDb(DbalExpressionResult $expression, $value, string $modifier): DbalExpressionResult
+	protected function evaluateInDb(
+		DbalExpressionResult $expression,
+		mixed $value,
+		string $modifier,
+	): DbalExpressionResult
 	{
 		return $expression->append("<= $modifier", $value);
 	}