Add orderByPriority Method for Custom Sorting in Query Builder V2

src/Illuminate/Database/Query/Builder.php

@@ -2614,6 +2614,39 @@ public function orderBy($column, $direction = 'asc')
         return $this;
     }
 
+    /**
+     * Apply custom ordering to a query based on a priority array.
+     *
+     * @param  string  $column
+     * @param  array  $priority
+     * @param  string  $direction
+     * @return $this
+     *
+     * @throws \InvalidArgumentException
+     */
+    public function orderByPriority($column, array $priority, $direction = 'asc')
+    {
+        $direction = strtolower($direction);
+
+        if (! in_array($direction, ['asc', 'desc'], true)) {
+            throw new InvalidArgumentException('Order direction must be "asc" or "desc".');
+        }
+
+        if (count($priority) === 0) {
+            throw new InvalidArgumentException('Order priority array must not be empty.');
+        }
+
+        $grammar = $this->getGrammar();
+
+        if (! method_exists($grammar, 'orderByPriority')) {
+            throw new RuntimeException('The "orderByPriority" function is not supported by this database.');
+        }
+
+        $this->orderByRaw($grammar->orderByPriority($column, $priority, $direction), $priority);
+
+        return $this;
+    }
+
     /**
      * Add a descending "order by" clause to the query.
      *

src/Illuminate/Database/Query/Grammars/MariaDbGrammar.php

@@ -53,4 +53,19 @@ public function useLegacyGroupLimit(Builder $query)
     {
         return false;
     }
+
+    /**
+     * Apply custom ordering to a query based on a priority array.
+     *
+     * @param  $column
+     * @param  array  $priority
+     * @param  $direction
+     * @return string
+     */
+    public function orderByPriority($column, array $priority, $direction = 'asc')
+    {
+        $placeholders = implode(',', array_fill(0, count($priority), '?'));
+
+        return "FIELD($column, $placeholders) $direction";
+    }
 }

src/Illuminate/Database/Query/Grammars/MySqlGrammar.php

@@ -524,4 +524,19 @@ protected function wrapJsonBooleanSelector($value)
 
         return 'json_extract('.$field.$path.')';
     }
+
+    /**
+     * Apply custom ordering to a query based on a priority array.
+     *
+     * @param  $column
+     * @param  array  $priority
+     * @param  $direction
+     * @return string
+     */
+    public function orderByPriority($column, array $priority, $direction = 'asc')
+    {
+        $placeholders = implode(',', array_fill(0, count($priority), '?'));
+
+        return "FIELD($column, $placeholders) $direction";
+    }
 }

src/Illuminate/Database/Query/Grammars/PostgresGrammar.php

@@ -772,4 +772,25 @@ public function substituteBindingsIntoRawSql($sql, $bindings)
 
         return $query;
     }
+
+    /**
+     * Apply custom ordering to a query based on a priority array.
+     *
+     * @param  $column
+     * @param  array  $priority
+     * @param  $direction
+     * @return string
+     */
+    public function orderByPriority($column, array $priority, $direction = 'asc')
+    {
+        $cases = [];
+
+        foreach ($priority as $index => $value) {
+            $cases[] = "WHEN {$column} = ? THEN {$index}";
+        }
+
+        $caseStatement = 'CASE '.implode(' ', $cases).' ELSE '.count($priority).' END';
+
+        return "{$caseStatement} {$direction}";
+    }
 }

src/Illuminate/Database/Query/Grammars/SQLiteGrammar.php

@@ -456,4 +456,25 @@ protected function wrapJsonSelector($value)
 
         return 'json_extract('.$field.$path.')';
     }
+
+    /**
+     * Apply custom ordering to a query based on a priority array.
+     *
+     * @param  $column
+     * @param  array  $priority
+     * @param  $direction
+     * @return string
+     */
+    public function orderByPriority($column, array $priority, $direction = 'asc')
+    {
+        $cases = [];
+
+        foreach ($priority as $index => $value) {
+            $cases[] = "WHEN {$column} = ? THEN {$index}";
+        }
+
+        $caseStatement = 'CASE '.implode(' ', $cases).' ELSE '.count($priority).' END';
+
+        return "{$caseStatement} {$direction}";
+    }
 }

src/Illuminate/Database/Query/Grammars/SqlServerGrammar.php

@@ -581,4 +581,23 @@ protected function wrapTableValuedFunction($table)
 
         return $table;
     }
+
+    /**
+     * @param  $column
+     * @param  array  $priority
+     * @param  $direction
+     * @return string
+     */
+    public function orderByPriority($column, array $priority, $direction = 'asc')
+    {
+        $cases = [];
+
+        foreach ($priority as $index => $value) {
+            $cases[] = "WHEN {$column} = ? THEN {$index}";
+        }
+
+        $caseStatement = 'CASE '.implode(' ', $cases).' ELSE '.count($priority).' END';
+
+        return "{$caseStatement} {$direction}";
+    }
 }

tests/Database/DatabaseMariaDbQueryGrammarTest.php

@@ -28,4 +28,11 @@ public function testToRawSql()
 
         $this->assertSame('select * from "users" where \'Hello\\\'World?\' IS NOT NULL AND "email" = \'foo\'', $query);
     }
+
+    public function testOrderByPriority()
+    {
+        $grammar = new MariaDbGrammar;
+        $queryString = $grammar->orderByPriority('name', ['john', 'doe']);
+        $this->assertSame('FIELD(name, ?,?) asc', $queryString);
+    }
 }

tests/Database/DatabaseMySqlQueryGrammarTest.php

@@ -28,4 +28,11 @@ public function testToRawSql()
 
         $this->assertSame('select * from "users" where \'Hello\\\'World?\' IS NOT NULL AND "email" = \'foo\'', $query);
     }
+
+    public function testOrderByPriority()
+    {
+        $grammar = new MySqlGrammar;
+        $queryString = $grammar->orderByPriority('name', ['john', 'doe']);
+        $this->assertSame('FIELD(name, ?,?) asc', $queryString);
+    }
 }

tests/Database/DatabasePostgresQueryGrammarTest.php

@@ -28,4 +28,11 @@ public function testToRawSql()
 
         $this->assertSame('select * from "users" where \'{}\' ? \'Hello\\\'\\\'World?\' AND "email" = \'foo\'', $query);
     }
+
+    public function testOrderByPriority()
+    {
+        $grammar = new PostgresGrammar;
+        $queryString = $grammar->orderByPriority('name', ['john', 'doe']);
+        $this->assertSame('CASE WHEN name = ? THEN 0 WHEN name = ? THEN 1 ELSE 2 END asc', $queryString);
+    }
 }

tests/Database/DatabaseSQLiteQueryGrammarTest.php

@@ -28,4 +28,11 @@ public function testToRawSql()
 
         $this->assertSame('select * from "users" where \'Hello\'\'World?\' IS NOT NULL AND "email" = \'foo\'', $query);
     }
+
+    public function testOrderByPriority()
+    {
+        $grammar = new SQLiteGrammar;
+        $queryString = $grammar->orderByPriority('name', ['john', 'doe']);
+        $this->assertSame('CASE WHEN name = ? THEN 0 WHEN name = ? THEN 1 ELSE 2 END asc', $queryString);
+    }
 }

tests/Database/DatabaseSqlServerQueryGrammarTest.php

@@ -28,4 +28,11 @@ public function testToRawSql()
 
         $this->assertSame("select * from [users] where 'Hello''World?' IS NOT NULL AND [email] = 'foo'", $query);
     }
+
+    public function testOrderByPriority()
+    {
+        $grammar = new SqlServerGrammar;
+        $queryString = $grammar->orderByPriority('name', ['john', 'doe']);
+        $this->assertSame('CASE WHEN name = ? THEN 0 WHEN name = ? THEN 1 ELSE 2 END asc', $queryString);
+    }
 }