[Feature] Allow custom sort methods to be implemented on adapters

See example in sorting chapter in the docs.

Closes #549

Author: lindyhopchris

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+### 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.

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);
+    }
+
+}
+```

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);
     }
 
     /**