feat: add sortUsing function to column for custom sorting (#2066)

xabec · web-flow · commit 2210f7f413ee · 2026-02-07T14:39:27.000-03:00
* feat: add sortUsing function to column for custom sorting

* fix: CustomSortTest
diff --git a/src/Column.php b/src/Column.php
@@ -2,6 +2,7 @@
 
 namespace PowerComponents\LivewirePowerGrid;
 
+use Closure;
 use Illuminate\Support\Traits\Macroable;
 use Livewire\Wireable;
 
@@ -41,6 +42,8 @@ final class Column implements Wireable
 
     public bool $sortable = false;
 
+    public ?Closure $sortCallback = null;
+
     public bool $index = false;
 
     public array $properties = [];
@@ -175,6 +178,21 @@ public function sortable(): Column
         return $this;
     }
 
+    /**
+     * Sets a custom sorting callback for this column.
+     * The callback receives the query builder and sort direction.
+     */
+    public function sortUsing(Closure $callback): Column
+    {
+        $this->enableSort();
+
+        $this->sortable = true;
+
+        $this->sortCallback = $callback;
+
+        return $this;
+    }
+
     /**
      * Field in the database
      */
@@ -289,7 +307,12 @@ public function template(): Column
 
     public function toLivewire(): array
     {
-        return (array) $this;
+        $data = (array) $this;
+
+        // Closures cannot be serialized, exclude them
+        unset($data['sortCallback']);
+
+        return $data;
     }
 
     public static function fromLivewire($value)
diff --git a/src/Concerns/Sorting.php b/src/Concerns/Sorting.php
@@ -115,4 +115,23 @@ public function updatedSortField(): void
             data_set($this->setUp, 'lazy.items', 0);
         }
     }
+
+    /**
+     * Get the sort callback for a given field from the columns definition.
+     * Returns null if no custom callback is defined.
+     */
+    public function getSortCallback(string $field): ?\Closure
+    {
+        $columns = $this->columns();
+
+        foreach ($columns as $column) {
+            $columnDataField = data_get($column, 'dataField');
+
+            if ($columnDataField === $field && data_get($column, 'sortCallback') instanceof \Closure) {
+                return $column->sortCallback;
+            }
+        }
+
+        return null;
+    }
 }
diff --git a/src/DataSource/Processors/Collection/Pipelines/Sorting.php b/src/DataSource/Processors/Collection/Pipelines/Sorting.php
@@ -17,19 +17,52 @@ public function handle(Collection $collection, Closure $next): Collection
         }
 
         if ($this->component->multiSort) {
-            $sortArray = [];
+            return $next($this->applyMultipleSort($collection));
+        }
+
+        return $next($this->applySingleSort($collection, $this->component->sortField, $this->component->sortDirection));
+    }
+
+    private function applySingleSort(Collection $collection, string $sortField, string $direction): Collection
+    {
+        $sortCallback = $this->component->getSortCallback($sortField);
+
+        if ($sortCallback !== null) {
+            return $sortCallback($collection, $direction);
+        }
+
+        $isDescending = $direction === 'desc';
 
-            foreach ($this->component->sortArray as $sortField => $sortDirection) {
-                $sortArray[] = [$sortField, $sortDirection];
+        return $collection->sortBy($sortField, SORT_REGULAR, $isDescending);
+    }
+
+    private function applyMultipleSort(Collection $collection): Collection
+    {
+        $sortArray = [];
+        $callbackFields = [];
+
+        foreach ($this->component->sortArray as $sortField => $sortDirection) {
+            $sortCallback = $this->component->getSortCallback($sortField);
+
+            if ($sortCallback !== null) {
+                $callbackFields[] = ['field' => $sortField, 'direction' => $sortDirection, 'callback' => $sortCallback];
+
+                continue;
             }
 
-            return $next($collection->sortBy($sortArray));
+            $sortArray[] = [$sortField, $sortDirection];
         }
 
-        $isDescending = $this->component->sortDirection === 'desc';
+        // Apply standard sorting first
+        if (filled($sortArray)) {
+            $collection = $collection->sortBy($sortArray);
+        }
 
-        $sorted = $collection->sortBy($this->component->sortField, SORT_REGULAR, $isDescending);
+        // Apply callback sorting
+        foreach ($callbackFields as $callbackField) {
+            $collection = $callbackField['callback']($collection, $callbackField['direction']);
+        }
 
-        return $next($sorted);
+        return $collection;
     }
 }
diff --git a/src/DataSource/Processors/Database/Pipelines/Sorting.php b/src/DataSource/Processors/Database/Pipelines/Sorting.php
@@ -23,19 +23,37 @@ public function handle(mixed $query, Closure $next): mixed
             if ($this->component->multiSort) {
                 $this->applyMultipleSort($query);
             } else {
-                $query->orderBy(
-                    $this->makeSortField($this->component->sortField),
-                    $this->component->sortDirection
-                );
+                $this->applySingleSort($query, $this->component->sortField, $this->component->sortDirection);
             }
         }
 
         return $next($query);
     }
 
+    private function applySingleSort(EloquentBuilder|MorphToMany|QueryBuilder $query, string $sortField, string $direction): void
+    {
+        $sortCallback = $this->component->getSortCallback($sortField);
+
+        if ($sortCallback !== null) {
+            $sortCallback($query, $direction);
+
+            return;
+        }
+
+        $query->orderBy($this->makeSortField($sortField), $direction);
+    }
+
     private function applyMultipleSort(EloquentBuilder|MorphToMany|QueryBuilder $results): void
     {
         foreach ($this->component->sortArray as $sortField => $direction) {
+            $sortCallback = $this->component->getSortCallback($sortField);
+
+            if ($sortCallback !== null) {
+                $sortCallback($results, $direction);
+
+                continue;
+            }
+
             $results->orderBy($this->makeSortField($sortField), $direction);
         }
     }
diff --git a/tests/Concerns/Components/DishesCustomSortCollectionTable.php b/tests/Concerns/Components/DishesCustomSortCollectionTable.php
@@ -0,0 +1,85 @@
+<?php
+
+namespace PowerComponents\LivewirePowerGrid\Tests\Concerns\Components;
+
+use Illuminate\Support\Collection;
+use PowerComponents\LivewirePowerGrid\{Column, Facades\PowerGrid, PowerGridComponent, PowerGridFields};
+
+class DishesCustomSortCollectionTable extends PowerGridComponent
+{
+    public string $tableName = 'dishes-custom-sort-collection-table';
+
+    public function datasource(): Collection
+    {
+        return collect([
+            ['id' => 1, 'name' => 'Zebra Dish', 'price' => 100.00, 'calories' => 300],
+            ['id' => 2, 'name' => 'Apple Pie', 'price' => 50.00, 'calories' => 200],
+            ['id' => 3, 'name' => 'Banana Split', 'price' => 75.00, 'calories' => 400],
+            ['id' => 4, 'name' => 'Cherry Tart', 'price' => 25.00, 'calories' => 100],
+            ['id' => 5, 'name' => 'Donut', 'price' => 10.00, 'calories' => 500],
+        ]);
+    }
+
+    public function setUp(): array
+    {
+        return [
+            PowerGrid::header()
+                ->showSearchInput(),
+
+            PowerGrid::footer()
+                ->showPerPage()
+                ->showRecordCount(),
+        ];
+    }
+
+    public function fields(): PowerGridFields
+    {
+        return PowerGrid::fields()
+            ->add('id')
+            ->add('name')
+            ->add('price')
+            ->add('calories');
+    }
+
+    public function columns(): array
+    {
+        return [
+            Column::make('Id', 'id')
+                ->sortable(),
+
+            Column::make('Name', 'name')
+                ->sortable(),
+
+            Column::make('Price', 'price')
+                ->sortUsing(function (Collection $collection, string $direction) {
+                    // Custom sort: sort by price with rounding to nearest 50
+                    return $collection->sortBy(function ($item) {
+                        return round(data_get($item, 'price') / 50) * 50;
+                    }, SORT_REGULAR, $direction === 'desc');
+                }),
+
+            Column::make('Calories', 'calories')
+                ->sortUsing(function (Collection $collection, string $direction) {
+                    // Custom sort: sort by calories in groups (low/medium/high)
+                    return $collection->sortBy(function ($item) {
+                        $calories = data_get($item, 'calories');
+                        if ($calories <= 200) {
+                            return 1; // Low
+                        }
+                        if ($calories <= 400) {
+                            return 2; // Medium
+                        }
+
+                        return 3; // High
+                    }, SORT_REGULAR, $direction === 'desc');
+                }),
+
+            Column::action('Action'),
+        ];
+    }
+
+    public function setTestThemeClass(string $themeClass): void
+    {
+        config(['livewire-powergrid.theme' => $themeClass]);
+    }
+}
diff --git a/tests/Concerns/Components/DishesCustomSortTable.php b/tests/Concerns/Components/DishesCustomSortTable.php
@@ -0,0 +1,68 @@
+<?php
+
+namespace PowerComponents\LivewirePowerGrid\Tests\Concerns\Components;
+
+use Illuminate\Database\Eloquent\Builder;
+use PowerComponents\LivewirePowerGrid\{Column, Facades\PowerGrid, PowerGridComponent, PowerGridFields};
+use PowerComponents\LivewirePowerGrid\Tests\Concerns\Models\Dish;
+
+class DishesCustomSortTable extends PowerGridComponent
+{
+    public string $tableName = 'dishes-custom-sort-table';
+
+    public function setUp(): array
+    {
+        return [
+            PowerGrid::header()
+                ->showSearchInput(),
+
+            PowerGrid::footer()
+                ->showPerPage()
+                ->showRecordCount(),
+        ];
+    }
+
+    public function datasource(): Builder
+    {
+        return Dish::query();
+    }
+
+    public function fields(): PowerGridFields
+    {
+        return PowerGrid::fields()
+            ->add('id')
+            ->add('name')
+            ->add('price')
+            ->add('calories');
+    }
+
+    public function columns(): array
+    {
+        return [
+            Column::make('Id', 'id')
+                ->sortable(),
+
+            Column::make('Name', 'name')
+                ->sortable(),
+
+            Column::make('Price', 'price')
+                ->sortUsing(function ($query, string $direction) {
+                    // Custom sort: sort by price, but nulls go last
+                    $query->orderByRaw("price IS NULL, price {$direction}");
+                }),
+
+            Column::make('Calories', 'calories')
+                ->sortUsing(function ($query, string $direction) {
+                    // Custom sort: multiply calories by a factor and sort
+                    $query->orderByRaw("calories * 2 {$direction}");
+                }),
+
+            Column::action('Action'),
+        ];
+    }
+
+    public function setTestThemeClass(string $themeClass): void
+    {
+        config(['livewire-powergrid.theme' => $themeClass]);
+    }
+}
diff --git a/tests/Feature/CustomSortTest.php b/tests/Feature/CustomSortTest.php
