Merge branch '2.x' into develop

lindyhopchris · lindyhopchris · commit 8c6488e8c172 · 2020-09-09T14:12:21.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -24,6 +24,17 @@ for the soft delete attribute now defaults to the camel-case version of the mode
 column `deleted_at` previously defaulted to the JSON API field `deleted-at`, whereas now it will
 default to `deletedAt`. To continue to use dash-case, set the `softDeleteField` property on your adapter.
 
+## [2.2.0] - 2020-09-09
+
+### Added
+- [#549](https://github.com/cloudcreativity/laravel-json-api/issues/549)
+Can now add sort methods to an Eloquent adapter if sorting is more complex than just sorting by
+a column value.
+
+### Fixed
+- The error translator will now detect if the translated value is identical to the translation
+key path, and return `null` when it is. This fixes behaviour that changed in Laravel 7.28.
+
 ## [2.1.0] - 2020-09-04
 
 ### Added
diff --git a/docs/fetching/sorting.md b/docs/fetching/sorting.md
@@ -142,3 +142,25 @@ class Adapter extends AbstractAdapter
 
 }
 ```
+
+To implement more complex sorting where you need access to the Eloquent query builder instance,
+you can add methods to your adapter. The method name must follow the pattern `sortBy<Name>`,
+where `<Name>` is the camel cased name of the JSON API sort field.
+
+For example, if you had a JSON API sort field called `likes`, you could implement the
+`sortByLikes` method on your adapter. This will receive the query builder instance and
+the direction of the sort (either `asc` or `desc`).
+
+```php
+class Adapter extends AbstractAdapter
+{
+    // ...
+
+    protected function sortByLikes($query, $direction): void
+    {
+        $query->withCount('likes')
+            ->orderBy('likes_count', $direction);
+    }
+
+}
+```
diff --git a/src/Eloquent/Concerns/SortsModels.php b/src/Eloquent/Concerns/SortsModels.php
@@ -101,13 +101,21 @@ protected function defaultSort()
     /**
      * @param Builder $query
      * @param SortParameterInterface $param
+     * @return void
      */
     protected function sortBy($query, SortParameterInterface $param)
     {
+        $direction = $param->isAscending() ? 'asc' : 'desc';
+        $method = 'sortBy' . Str::classify($param->getField());
+
+        if (method_exists($this, $method)) {
+            $this->{$method}($query, $direction);
+            return;
+        }
+
         $column = $this->getQualifiedSortColumn($query, $param->getField());
-        $order = $param->isAscending() ? 'asc' : 'desc';
 
-        $query->orderBy($column, $order);
+        $query->orderBy($column, $direction);
     }
 
     /**
