feat: order by nulls first/last (resolves #31)

Author: tpetry

README.md

@@ -1163,6 +1163,26 @@ $query->whereIntegerArrayMatches('tags', '3&4&(5|6)&!7');
 
 ### Order By
 
+#### NULLS FIRST/LAST
+
+By default, `NULL` values are sorted before everything in descending order and after everything in ascending order.
+This may not be your preferred way of ordering when e.g. displaying in a table to users.
+With the nulls first/last option, you can specify the exact behaviour you want:
+
+```php
+$query->orderBy($column, string $direction = 'asc'|'desc', string $nulls = 'default'|'first'|'last');
+$query->orderByNullsFirst($column, string $direction = 'asc'|'desc', string $nulls = 'default'|'first'|'last');
+$query->orderByNullsLast($column, string $direction = 'asc'|'desc', string $nulls = 'default'|'first'|'last');
+
+// Sort the table by the age descending with all NULL values presented last.
+$query->orderBy('age', 'desc', nulls: 'last');
+$query->orderByNullsLast('age', 'desc');
+```
+
+> [!WARNING]
+> You have to create a matching index when using a non-default sorting order - a standard one does not work!
+> The exact index `$table->index('age DESC NULLS LAST')` matches the query or `$table->index('age NULLS FIRT')` because of the default ascending column order.
+
 #### Vector Similarity
 
 With the `orderByVectorSimilarity` method you can compare a column storing embeddings to other embeddings.

src/Query/BuilderOrder.php

@@ -10,6 +10,64 @@
 
 trait BuilderOrder
 {
+    /**
+     * Add an "order by" clause to the query.
+     *
+     * @param \Closure|\Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder<*>|\Illuminate\Contracts\Database\Query\Expression|string $column
+     * @param 'asc'|'desc' $direction
+     * @param 'default'|'first'|'last' $nulls
+     */
+    public function orderBy($column, $direction = 'asc', $nulls = 'default'): static
+    {
+        if ($this->isQueryable($column)) {
+            [$query, $bindings] = $this->createSub($column);
+
+            $column = new Expression('('.$query.')');
+
+            $this->addBinding($bindings, $this->unions ? 'unionOrder' : 'order');
+        }
+
+        $direction = strtolower($direction);
+        if (!\in_array($direction, ['asc', 'desc'], true)) {
+            throw new InvalidArgumentException('Order direction must be "asc" or "desc".');
+        }
+
+        $nulls = strtolower($nulls);
+        if (!\in_array($nulls, ['default', 'first', 'last'], true)) {
+            throw new InvalidArgumentException('Nulls direction must be "default", "first" or "last".');
+        }
+
+        $this->{$this->unions ? 'unionOrders' : 'orders'}[] = [
+            'column' => $column,
+            'direction' => $direction,
+            'nulls' => $nulls,
+        ];
+
+        return $this;
+    }
+
+    /**
+     * Add an "order by nulls first" clause to the query.
+     *
+     * @param \Closure|\Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder<*>|\Illuminate\Contracts\Database\Query\Expression|string $column
+     * @param 'asc'|'desc' $direction
+     */
+    public function orderByNullsFirst($column, string $direction = 'asc'): static
+    {
+        return $this->orderBy($column, $direction, 'first');
+    }
+
+    /**
+     * Add an "order by nulls last" clause to the query.
+     *
+     * @param \Closure|\Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder<*>|\Illuminate\Contracts\Database\Query\Expression|string $column
+     * @param 'asc'|'desc' $direction
+     */
+    public function orderByNullsLast($column, string $direction = 'asc'): static
+    {
+        return $this->orderBy($column, $direction, 'last');
+    }
+
     /**
      * Add a vector-similarity "order by" clause to the query.
      *

src/Query/Grammar.php

@@ -11,6 +11,7 @@ class Grammar extends PostgresGrammar
 {
     use GrammarCte;
     use GrammarFullText;
+    use GrammarOrder;
     use GrammarReturning;
     use GrammarWhere;
 

src/Query/GrammarOrder.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tpetry\PostgresqlEnhanced\Query;
+
+use Illuminate\Database\Query\Builder;
+
+trait GrammarOrder
+{
+    /**
+     * Compile the query orders to an array.
+     *
+     * @param array $orders
+     */
+    protected function compileOrdersToArray(Builder $query, $orders): array
+    {
+        return array_map(function ($order) {
+            $sql = $order['sql'] ?? "{$this->wrap($order['column'])} {$order['direction']}";
+
+            return match ($order['nulls'] ?? null) {
+                'first' => "{$sql} nulls first",
+                'last' => "{$sql} nulls last",
+                default => $sql,
+            };
+        }, $orders);
+    }
+}

tests/Query/OrderTest.php

@@ -8,6 +8,48 @@
 
 class OrderTest extends TestCase
 {
+    public function testNullsDefault(): void
+    {
+        $this->getConnection()->unprepared('CREATE TABLE example (col int)');
+
+        $queries = $this->withQueryLog(function (): void {
+            $this->getConnection()->table('example')->orderBy('col')->get();
+            $this->getConnection()->table('example')->orderBy('col', nulls: 'default')->get();
+        });
+        $this->assertEquals(
+            ['select * from "example" order by "col" asc', 'select * from "example" order by "col" asc'],
+            array_column($queries, 'query'),
+        );
+    }
+
+    public function testNullsFirst(): void
+    {
+        $this->getConnection()->unprepared('CREATE TABLE example (col int)');
+
+        $queries = $this->withQueryLog(function (): void {
+            $this->getConnection()->table('example')->orderBy('col', nulls: 'first')->get();
+            $this->getConnection()->table('example')->orderByNullsFirst('col')->get();
+        });
+        $this->assertEquals(
+            ['select * from "example" order by "col" asc nulls first', 'select * from "example" order by "col" asc nulls first'],
+            array_column($queries, 'query'),
+        );
+    }
+
+    public function testNullsLast(): void
+    {
+        $this->getConnection()->unprepared('CREATE TABLE example (col int)');
+
+        $queries = $this->withQueryLog(function (): void {
+            $this->getConnection()->table('example')->orderBy('col', nulls: 'last')->get();
+            $this->getConnection()->table('example')->orderByNullsLast('col')->get();
+        });
+        $this->assertEquals(
+            ['select * from "example" order by "col" asc nulls last', 'select * from "example" order by "col" asc nulls last'],
+            array_column($queries, 'query'),
+        );
+    }
+
     public function testVectorSimilarity(): void
     {
         if (!$this->getConnection()->table('pg_available_extensions')->where('name', 'vector')->exists()) {