Enable the usage of an alias for a column name when using Sorts (#164)

* allow for alias on sort

* Fix tests and add column name to sort class

* drop array syntax for aliasing allowed sorts
adjust documentation

* drop test for array syntax

* add hyperlink to readme

Author: dominikb

README.md

@@ -184,7 +184,7 @@ use Spatie\QueryBuilder\Filter;
 
 // GET /users?filter[name]=John
 $users = QueryBuilder::for(User::class)
-	->allowedFilters(Filter::exact('name', 'user_name')) // public filter, column name
+    ->allowedFilters(Filter::exact('name', 'user_name')) // public filter, column name
     ->get();
 // filter by the column 'user_name'
 ```
@@ -383,6 +383,21 @@ $users = QueryBuilder::for(User::class)
 // $users will be sorted by name in ascending order with a secondary sort on street in descending order.
 ```
 
+#### Using an alias for sorting
+
+There may be occasions where it is not appropriate to expose the column name to the user.
+
+Similar to using [an alias when filtering](#property-column-alias) you can do this with for sorts as well.
+
+The column name can be passed as optional parameter and defaults to the property string.
+
+ ``` php
+ // GET /users?sort=-street
+ $users = QueryBuilder::for(User::class)
+    ->allowedSorts(Sort::field('street', 'actual_column_street')
+    ->get();
+ ```
+
 ### Selecting specific columns
 
 Sometimes you'll want to fetch only a couple fields to reduce the overall size of your SQL query. This can be done using the `fields` query parameter. The following fetch only the users' `id` and `name`

src/Filter.php

@@ -11,7 +11,7 @@
 
 class Filter
 {
-    /** @var string */
+    /** @var string|\Spatie\QueryBuilder\Filters\Filter */
     protected $filterClass;
 
     /** @var string */
@@ -23,7 +23,7 @@ class Filter
     /** @var Collection */
     protected $ignored;
 
-    public function __construct(string $property, $filterClass, $columnName = null)
+    public function __construct(string $property, $filterClass, ?string $columnName = null)
     {
         $this->property = $property;
 
@@ -47,7 +47,7 @@ public function filter(Builder $builder, $value)
         ($filterClass)($builder, $valueToFilter, $this->columnName);
     }
 
-    public static function exact(string $property, $columnName = null) : self
+    public static function exact(string $property, ?string $columnName = null) : self
     {
         return new static($property, FiltersExact::class, $columnName);
     }

src/QueryBuilder.php

@@ -317,7 +317,7 @@ protected function filterDuplicates(Collection $sorts): Collection
 
         return $sorts->reject(function (string $sort) use ($orders) {
             $toSort = [
-                'column' => ltrim($sort, '-'),
+                'column'    => ltrim($sort, '-'),
                 'direction' => ($sort[0] === '-') ? 'desc' : 'asc',
             ];
             foreach ($orders as $order) {

src/Sort.php

@@ -12,17 +12,24 @@ class Sort
     /** @var string */
     protected $sortClass;
 
-    /** @var string */
+    /** @var string|\Spatie\QueryBuilder\Sorts\Sort */
     protected $property;
 
     /** @var string */
     protected $defaultDirection;
 
-    public function __construct(string $property, $sortClass)
+    /** @var string */
+    protected $columnName;
+
+    public function __construct(string $property, $sortClass, ?string $columnName = null)
     {
         $this->property = ltrim($property, '-');
+
         $this->sortClass = $sortClass;
+
         $this->defaultDirection = static::parsePropertyDirection($property);
+
+        $this->columnName = $columnName ?? $property;
     }
 
     public static function parsePropertyDirection(string $property): string
@@ -36,17 +43,17 @@ public function sort(Builder $builder, ?bool $descending = null)
 
         $descending = $descending ?? ($this->defaultDirection === SortDirection::DESCENDING);
 
-        ($sortClass)($builder, $descending, $this->property);
+        ($sortClass)($builder, $descending, $this->columnName);
     }
 
-    public static function field(string $property) : self
+    public static function field(string $property, ?string $columnName = null) : self
     {
-        return new static($property, SortsField::class);
+        return new static($property, SortsField::class, $columnName);
     }
 
-    public static function custom(string $property, $sortClass) : self
+    public static function custom(string $property, $sortClass, ?string $columnName = null) : self
     {
-        return new static($property, $sortClass);
+        return new static($property, $sortClass, $columnName);
     }
 
     public function getProperty(): string
@@ -67,4 +74,9 @@ private function resolveSortClass(): CustomSort
 
         return new $this->sortClass;
     }
+
+    public function getColumnName(): string
+    {
+        return $this->columnName;
+    }
 }

tests/SortTest.php

@@ -7,6 +7,7 @@
 use Illuminate\Support\Facades\DB;
 use Spatie\QueryBuilder\QueryBuilder;
 use Illuminate\Database\Eloquent\Builder;
+use Spatie\QueryBuilder\Sorts\SortsField;
 use Spatie\QueryBuilder\Tests\Models\TestModel;
 use Spatie\QueryBuilder\Exceptions\InvalidSortQuery;
 use Spatie\QueryBuilder\Sorts\Sort as SortInterface;
@@ -177,6 +178,49 @@ public function __invoke(Builder $query, $descending, string $property) : Builde
         $this->assertSortedAscending($sortedModels, 'name');
     }
 
+    /** @test */
+    public function it_can_take_an_argument_for_custom_column_name_resolution()
+    {
+        $sort = Sort::custom('property_name', SortsField::class, 'property_column_name');
+
+        $this->assertInstanceOf(Sort::class, $sort);
+        $this->assertClassHasAttribute('columnName', get_class($sort));
+    }
+
+    /** @test */
+    public function it_sets_property_column_name_to_property_name_by_default()
+    {
+        $sort = Sort::custom('property_name', SortsField::class);
+
+        $this->assertEquals($sort->getProperty(), $sort->getColumnName());
+    }
+
+    /** @test */
+    public function it_resolves_queries_using_property_column_name()
+    {
+        $sort = Sort::custom('nickname', SortsField::class, 'name');
+
+        $testModel = TestModel::create(['name' => 'zzzzzzzz']);
+
+        $models = $this
+            ->createQueryFromSortRequest('nickname')
+            ->allowedSorts($sort)
+            ->get();
+
+        $this->assertSorted($models, 'name');
+        $this->assertTrue($testModel->is($models->last()));
+    }
+
+    /** @test */
+    public function it_can_sort_descending_with_an_alias()
+    {
+        $this->createQueryFromSortRequest('-exposed_property_name')
+            ->allowedSorts(Sort::field('exposed_property_name', 'name'))
+            ->get();
+
+        $this->assertQueryExecuted('select * from "test_models" order by "name" desc');
+    }
+
     protected function createQueryFromSortRequest(string $sort): QueryBuilder
     {
         $request = new Request([