feat: add sorting functionality to user list retrieval

Author: aspirantzhang

contexts/Authorization/Application/Coordinators/UserIdentityCoordinator.php

@@ -61,7 +61,12 @@ public function getUserList(GetUserListDTO $data): LengthAwarePaginator
             new GlobalPermissionPolicy('user.list'),
         ])->check();
 
-        return $this->repository->paginate($data->currentPage, $data->perPage, $data->toCriteria());
+        return $this->repository->paginate(
+            $data->currentPage,
+            $data->perPage,
+            $data->toCriteria(),
+            $data->toSorting()
+        );
     }
 
     public function updateUser(int $id, UpdateUserDTO $data): UserIdentity

contexts/Authorization/Application/DTOs/User/GetUserListDTO.php

@@ -4,8 +4,12 @@
 
 namespace Contexts\Authorization\Application\DTOs\User;
 
-class GetUserListDTO
+use Contexts\Shared\Application\BaseGetListDTO;
+
+class GetUserListDTO extends BaseGetListDTO
 {
+    protected const ALLOWED_SORT_FIELDS = ['id', 'created_at'];
+
     public function __construct(
         public readonly ?string $id,
         public readonly ?string $email,
@@ -14,21 +18,30 @@ public function __construct(
         public readonly ?array $createdAtRange,
         public readonly int $currentPage,
         public readonly int $perPage,
+        public readonly ?array $sorting
     ) {}
 
     public static function fromRequest(array $data): self
     {
+        $merged = array_merge($data, self::convertFiltersToCriteria($data['filters'] ?? []));
+
         return new self(
-            $data['id'] ?? null,
-            $data['email'] ?? null,
-            $data['display_name'] ?? null,
-            $data['status'] ?? null,
-            $data['created_at_range'] ?? null,
-            $data['current_page'] ?? 1,
-            $data['per_page'] ?? 10,
+            $merged['id'] ?? null,
+            $merged['email'] ?? null,
+            $merged['display_name'] ?? null,
+            $merged['status'] ?? null,
+            $merged['created_at_range'] ?? null,
+            $merged['current_page'] ?? 1,
+            $merged['per_page'] ?? 10,
+            self::normalizeAndFilterSorting($merged)
         );
     }
 
+    public function toSorting(): array
+    {
+        return $this->sorting;
+    }
+
     public function toCriteria(): array
     {
         return [

contexts/Authorization/Domain/Repositories/UserRepository.php

@@ -17,7 +17,7 @@ public function getById(UserId $userId): UserIdentity;
 
     public function update(UserIdentity $user): UserIdentity;
 
-    public function paginate(int $currentPage = 1, int $perPage = 10, array $criteria = []): LengthAwarePaginator;
+    public function paginate(int $currentPage = 1, int $perPage = 10, array $criteria = [], array $sorting = []): LengthAwarePaginator;
 
     public function delete(UserIdentity $user): void;
 

contexts/Authorization/Infrastructure/Persistence/UserPersistence.php

@@ -67,9 +67,12 @@ public function update(UserIdentity $user): UserIdentity
         return $record->toDomain($user->getEvents());
     }
 
-    public function paginate(int $currentPage = 1, int $perPage = 10, array $criteria = []): LengthAwarePaginator
+    public function paginate(int $currentPage = 1, int $perPage = 10, array $criteria = [], array $sorting = []): LengthAwarePaginator
     {
-        $paginator = UserRecord::query()->search($criteria)->paginate($perPage, ['*'], 'current_page', $currentPage);
+        $paginator = UserRecord::query()
+            ->search($criteria)
+            ->sorting($sorting)
+            ->paginate($perPage, ['*'], 'current_page', $currentPage);
 
         $paginator->getCollection()->transform(function ($record) {
             return $record->toDomain();

contexts/Authorization/Infrastructure/Records/UserRecord.php

@@ -13,6 +13,7 @@
 use Contexts\Authorization\Domain\UserIdentity\Models\UserIdentity;
 use Contexts\Authorization\Domain\UserIdentity\Models\UserStatus;
 use Contexts\Authorization\Infrastructure\RecordFactories\UserRecordFactory;
+use Contexts\Shared\Infrastructure\Traits\HasSortingScopeTrait;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Factories\Factory;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
@@ -34,6 +35,7 @@ class UserRecord extends Authenticatable
 {
     use HasApiTokens;
     use HasFactory;
+    use HasSortingScopeTrait;
     use Notifiable;
 
     protected $table = 'users';

contexts/Authorization/Presentation/Requests/User/GetUserListRequest.php

@@ -4,9 +4,9 @@
 
 namespace Contexts\Authorization\Presentation\Requests\User;
 
-use Contexts\Shared\Presentation\Requests\BaseRequest;
+use Contexts\Shared\Presentation\Requests\BaseListRequest;
 
-class GetUserListRequest extends BaseRequest
+class GetUserListRequest extends BaseListRequest
 {
     public function rules(): array
     {
@@ -15,10 +15,11 @@ public function rules(): array
             'display_name' => ['string', 'max:255'],
             'email' => ['email', 'max:255'],
             'status' => ['string', 'in:suspended,active'],
-            'created_at_range' => ['array', 'size:2'],
-            'created_at_range.*' => ['date'],
-            'current_page' => ['integer', 'gt:0'],
-            'per_page' => ['integer', 'gt:0'],
+            'created_at' => ['array', 'size:2'],
+            'created_at.*' => ['date_format:Y-m-d'],
+            ...$this->paginationRule(),
+            ...$this->filtersRule(),
+            ...$this->sortingRule(),
         ];
     }
 }

contexts/Authorization/Tests/Feature/UserTest.php

@@ -4,6 +4,7 @@
 
 use Contexts\Authorization\Domain\Policies\RolePolicy;
 use Contexts\Authorization\Infrastructure\Records\RoleRecord;
+use Contexts\Authorization\Infrastructure\Records\UserRecord;
 
 beforeEach(function () {
     Config::set('policies.authorization', [
@@ -74,6 +75,28 @@
     $response->assertStatus(200);
 });
 
+it('can get a list of users with sorting via api', function () {
+    $initialCount = UserRecord::count();
+
+    UserRecord::factory(3)->create();
+
+    $response = $this->get('users?sorting=[{"id":"id","desc":false}]');
+
+    $response->assertStatus(200);
+    $response->assertJsonCount(3 + $initialCount, 'data');
+
+    $responseIds = collect($response->json('data'))->pluck('id')->all();
+    $sortedIds = collect($responseIds)->sort()->values()->all();
+    expect($responseIds)->toBe($sortedIds);
+
+    $response = $this->get('users?sorting=[{"id":"id","desc":true}]');
+    $response->assertStatus(200);
+
+    $responseIds = collect($response->json('data'))->pluck('id')->all();
+    $sortedIds = collect($responseIds)->sortDesc()->values()->all();
+    expect($responseIds)->toBe($sortedIds);
+});
+
 it('can update a user via api', function () {
     $response = $this->postJson('users', [
         'email' => 'test@email.com',