feat: ability to filter and sort relation entities by pivot entry fields

Author: alexzarbn

src/Drivers/Standard/QueryBuilder.php

@@ -111,12 +111,16 @@ public function applyFiltersToQuery($query, Request $request): void
                 $relation = $this->relationsResolver->relationFromParamConstraint($filterDescriptor['field']);
                 $relationField = $this->relationsResolver->relationFieldFromParamConstraint($filterDescriptor['field']);
 
-                $query->{$or ? 'orWhereHas' : 'whereHas'}(
-                    $relation,
-                    function ($relationQuery) use ($relationField, $filterDescriptor) {
-                        $this->buildFilterQueryWhereClause($relationField, $filterDescriptor, $relationQuery);
-                    }
-                );
+                if ($relation === 'pivot') {
+                    $this->buildPivotFilterQueryWhereClause($relationField, $filterDescriptor, $query, $or);
+                } else {
+                    $query->{$or ? 'orWhereHas' : 'whereHas'}(
+                        $relation,
+                        function ($relationQuery) use ($relationField, $filterDescriptor) {
+                            $this->buildFilterQueryWhereClause($relationField, $filterDescriptor, $relationQuery);
+                        }
+                    );
+                }
             } else {
                 $this->buildFilterQueryWhereClause($this->getQualifiedFieldName($filterDescriptor['field']), $filterDescriptor, $query, $or);
             }
@@ -143,6 +147,26 @@ protected function buildFilterQueryWhereClause(string $field, array $filterDescr
         return $query;
     }
 
+    /**
+     * Builds filter's pivot query where clause based on the given filterable.
+     *
+     * @param string $field
+     * @param array $filterDescriptor
+     * @param Builder|Relation $query
+     * @param bool $or
+     * @return Builder|Relation
+     */
+    protected function buildPivotFilterQueryWhereClause(string $field, array $filterDescriptor, $query, bool $or = false)
+    {
+        if (!is_array($filterDescriptor['value'])) {
+            $query->{$or ? 'orWherePivot' : 'wherePivot'}($field, $filterDescriptor['operator'], $filterDescriptor['value']);
+        } else {
+            $query->{$or ? 'orWherePivotIn' : 'wherePivotIn'}($field, $filterDescriptor['value'], 'and', $filterDescriptor['operator'] === 'not in');
+        }
+
+        return $query;
+    }
+
     /**
      * Builds a complete field name with table.
      *
@@ -218,6 +242,11 @@ public function applySortingToQuery($query, Request $request): void
                 $relation = $this->relationsResolver->relationFromParamConstraint($sortableField);
                 $relationField = $this->relationsResolver->relationFieldFromParamConstraint($sortableField);
 
+                if ($relation === 'pivot') {
+                    $query->orderByPivot($relationField, $direction);
+                    continue;
+                }
+
                 /**
                  * @var Relation $relationInstance
                  */

tests/Feature/Relations/BelongsToMany/BelongsToManyRelationStandardIndexFilteringOperationsTest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Orion\Tests\Feature\Relations\BelongsToMany;
+
+use Illuminate\Support\Facades\Gate;
+use Orion\Tests\Feature\TestCase;
+use Orion\Tests\Fixtures\App\Models\Role;
+use Orion\Tests\Fixtures\App\Models\User;
+use Orion\Tests\Fixtures\App\Policies\GreenPolicy;
+
+class BelongsToManyRelationStandardIndexFilteringOperationsTest extends TestCase
+{
+    /** @test */
+    public function getting_a_list_of_relation_resources_filtered_by_pivot_field(): void
+    {
+        /** @var User $user */
+        $user = factory(User::class)->create();
+
+        $roleWithCustomName = factory(Role::class)->create();
+        $roleWithoutCustomName = factory(Role::class)->create();
+
+        $user->roles()->attach($roleWithCustomName, ['custom_name' => 'test-name']);
+        $user->roles()->attach($roleWithoutCustomName);
+
+        Gate::policy(User::class, GreenPolicy::class);
+        Gate::policy(Role::class, GreenPolicy::class);
+
+        $response = $this->post("/api/users/{$user->id}/roles/search", [
+            'filters' => [
+                ['field' => 'pivot.custom_name', 'operator' => '=', 'value' => 'test-name']
+            ]
+        ]);
+
+        $this->assertResourcesPaginated(
+            $response,
+            $this->makePaginator([$user->roles()->first()->toArray()], "users/{$user->id}/roles/search")
+        );
+    }
+}

tests/Feature/Relations/BelongsToMany/BelongsToManyRelationStandardIndexSortingOperationsTest.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Orion\Tests\Feature\Relations\BelongsToMany;
+
+use Illuminate\Support\Facades\Gate;
+use Orion\Tests\Feature\TestCase;
+use Orion\Tests\Fixtures\App\Models\Role;
+use Orion\Tests\Fixtures\App\Models\User;
+use Orion\Tests\Fixtures\App\Policies\GreenPolicy;
+
+class BelongsToManyRelationStandardIndexSortingOperationsTest extends TestCase
+{
+    /** @test */
+    public function getting_a_list_of_relation_resources_desc_sorted_by_pivot_field(): void
+    {
+        if ((float) app()->version() <= 8.0) {
+            $this->markTestSkipped('Unsupported framework version');
+        }
+
+        /** @var User $user */
+        $user = factory(User::class)->create();
+
+        $roleA = factory(Role::class)->create();
+        $roleB = factory(Role::class)->create();
+        $roleC = factory(Role::class)->create();
+
+        $user->roles()->attach($roleA, ['custom_name' => 'a']);
+        $user->roles()->attach($roleB, ['custom_name' => 'b']);
+        $user->roles()->attach($roleC, ['custom_name' => 'c']);
+
+        Gate::policy(User::class, GreenPolicy::class);
+        Gate::policy(Role::class, GreenPolicy::class);
+
+        $response = $this->withoutExceptionHandling()->post("/api/users/{$user->id}/roles/search", [
+            'sort' => [
+                ['field' => 'pivot.custom_name', 'direction' => 'desc']
+            ]
+        ]);
+
+        $this->assertResourcesPaginated(
+            $response,
+            $this->makePaginator($user->roles()->get()->reverse()->toArray(), "users/{$user->id}/roles/search")
+        );
+    }
+}

tests/Fixtures/app/Http/Controllers/UserRolesController.php

@@ -17,6 +17,16 @@ class UserRolesController extends RelationController
 
     protected $pivotFillable = ['custom_name', 'references'];
 
+    public function filterableBy(): array
+    {
+        return ['pivot.custom_name'];
+    }
+
+    public function sortableBy(): array
+    {
+        return ['pivot.custom_name'];
+    }
+
     public function includes(): array
     {
         return ['users'];