Sorting mechanism revised. The class DBExprOrderBySpec has been deprecated in favor of DBOrderSpec.

Author: rkrx

src/Builder/Expr/DBExprOrderBySpec.php

@@ -1,13 +1,16 @@
 <?php
 namespace Kir\MySQL\Builder\Expr;
 
+/**
+ * @deprecated
+ */
 class DBExprOrderBySpec implements OrderBySpecification {
-	/** @var array[] */
+	/** @var array<int, array{string, string}> */
 	private $fields = [];
-	
+
 	/**
-	 * @param array $spec
-	 * @param array $sortFieldsSpec
+	 * @param array<string|int, string> $spec
+	 * @param array<int, array{string, string}|array<string, string>> $sortFieldsSpec
 	 */
 	public function __construct($spec, $sortFieldsSpec) {
 		$expressions = [];
@@ -18,19 +21,28 @@ public function __construct($spec, $sortFieldsSpec) {
 			$expressions[$specReference] = $dbExpr;
 		}
 		foreach($sortFieldsSpec as $sortFieldSpec) {
-			if(array_key_exists(0, $sortFieldSpec) && array_key_exists($sortFieldSpec[0], $expressions)) {
-				$direction = 'ASC';
-				if(array_key_exists(1, $sortFieldSpec) && strtoupper($sortFieldSpec[1]) !== 'ASC') {
-					$direction = 'DESC';
+			if(array_key_exists(0, $sortFieldSpec)) {
+				if(array_key_exists($sortFieldSpec[0], $expressions)) {
+					$direction = 'ASC';
+					if(array_key_exists(1, $sortFieldSpec) && strtoupper($sortFieldSpec[1]) !== 'ASC') {
+						$direction = 'DESC';
+					}
+					$this->fields[] = [
+						$expressions[$sortFieldSpec[0]],
+						$direction
+					];
+				}
+			} else {
+				foreach($sortFieldSpec as $alias => $direction) {
+					$direction = strtoupper($direction) === 'DESC' ? 'DESC' : 'ASC';
+					if(array_key_exists($alias, $expressions)) {
+						$this->fields[] = [$expressions[$alias], $direction];
+					}
 				}
-				$this->fields[] = [
-					$expressions[$sortFieldSpec[0]],
-					$direction
-				];
 			}
 		}
 	}
-	
+
 	/**
 	 * Returns an array[], where each value is a [db-expression, sort-direction]
 	 * The sort-direction can be either ASC or DESC

src/Builder/Expr/DBOrderSpec.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Kir\MySQL\Builder\Expr;
+
+use RuntimeException;
+
+/**
+ * Defines fields that are sortable. Sortable fields have an alias.
+ * The alias can be passed as a sort specifier - along with the direction in which to sort.
+ */
+class DBOrderSpec implements DBOrderSpecInterface, OrderBySpecification {
+	/** @var array<string, string> */
+	private $sortSpecification;
+	/** @var array<string, string> */
+	private $sortingInstruction;
+	/** @var array<string, mixed> */
+	private $options;
+
+	/**
+	 * @param array<string, string> $sortSpecification
+	 * @param array<string, string> $sortingInstruction
+	 * @param array{max_sort_instructions?: positive-int} $options
+	 * @return static
+	 */
+	public static function from(array $sortSpecification, array $sortingInstruction, array $options = []) {
+		return new static($sortSpecification, $sortingInstruction, $options);
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function __construct(array $sortSpecification, array $sortingInstruction, array $options = []) {
+		$this->sortSpecification = $sortSpecification;
+		$this->sortingInstruction = $sortingInstruction;
+		$this->options = $options;
+	}
+
+	/**
+	 * @return array<int, array{string, string}>
+	 */
+	public function getFields() {
+		$fields = [];
+		$max = $this->options['max_sort_instructions'] ?? 16;
+		foreach($this->sortingInstruction as $alias => $direction) {
+			$direction = strtolower($direction) === 'desc' ? 'DESC' : 'ASC';
+			if(array_key_exists($alias, $this->sortSpecification)) {
+				$fields[] = [$this->sortSpecification[$alias], $direction];
+			}
+			if($max < 1) {
+				throw new RuntimeException();
+			}
+			$max--;
+		}
+		return $fields;
+	}
+}

src/Builder/Expr/DBOrderSpecInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Kir\MySQL\Builder\Expr;
+
+/**
+ * This interface is needed to allow new static in the deriving class
+ */
+interface DBOrderSpecInterface {
+	/**
+	 * @param array<string, string> $sortSpecification Key = Alias, Value = DB-Expression
+	 * @param array<string, string> $sortingInstruction Key = Alias, Value = Sortdirection ("ASC" | "DESC")
+	 * @param array{max_sort_instructions?: positive-int} $options
+	 */
+	public function __construct(array $sortSpecification, array $sortingInstruction, array $options = []);
+}

src/Builder/Expr/OrderBySpecification.php

@@ -3,10 +3,10 @@
 
 interface OrderBySpecification {
 	/**
-	 * Returns an array[], where each value is a [db-expression, sort-direction]
+	 * Returns an array<int, array{string, string}>, where each value is a [db-expression, sort-direction]
 	 * The sort-direction can be either ASC or DESC
 	 *
-	 * @return array[]
+	 * @return array<int, array{string, string}>
 	 */
 	public function getFields();
 }

src/Builder/Value/DBOptionalValue.php

@@ -5,14 +5,15 @@
 use Kir\MySQL\Builder\Helpers\RecursiveStructureAccess;
 
 class DBOptionalValue implements OptionalValue {
+	/** @var object|array<string, mixed> */
 	private $data;
 	/** @var string|string[] */
 	private $path;
 	/** @var callable|null */
 	private $validator;
 
 	/**
-	 * @param object|array<string, mixed>
+	 * @param object|array<string, mixed> $data
 	 * @param string|string[] $path
 	 * @param null|callable(): bool $validator
 	 */

tests/Builder/SelectTest.php

@@ -3,6 +3,7 @@
 
 use Kir\MySQL\Builder\Expr\DBExprFilter;
 use Kir\MySQL\Builder\Expr\DBExprOrderBySpec;
+use Kir\MySQL\Builder\Expr\DBOrderSpec;
 use Kir\MySQL\Builder\Expr\OptionalDBFilterMap;
 use Kir\MySQL\Builder\Expr\RequiredDBFilterMap;
 use Kir\MySQL\Builder\Expr\RequiredValueNotFoundException;
@@ -451,10 +452,10 @@ public function testSortSpecification() {
 		->field('t.field1')
 		->field('t.field2')
 		->from('t', 'test')
-		->orderBy(new DBExprOrderBySpec(['field1', 'field2' => 'REVERSE(t.field2)'], [['field2', 'ASC'], ['field1', 'DESC'], ['field3' => 'ASC']]))
+		->orderBy(new DBOrderSpec(['field1' => 't.field1', 'field2' => 'REVERSE(t.field2)', 'field4' => 't.field2'], ['field3' => 'ASC', 'field1' => 'ASC', 'field2' => 'ASC', 'field4' => 'ASC']))
 		->asString();
 
-		self::assertEquals("SELECT\n\tt.field1,\n\tt.field2\nFROM\n\ttest t\nORDER BY\n\tREVERSE(t.field2) ASC,\n\tfield1 DESC\n", $query);
+		self::assertEquals("SELECT\n\tt.field1,\n\tt.field2\nFROM\n\ttest t\nORDER BY\n\tt.field1 ASC,\n\tREVERSE(t.field2) ASC,\n\tt.field2 ASC\n", $query);
 	}
 
 	public function testVirtualTables() {