✨ allow searching explicitly for username or displayname (#3064)

app/Http/Controllers/API/v1/UserController.php

@@ -435,15 +435,15 @@ public function destroyMute(int $userId): JsonResponse {
 
     /**
      * @OA\Get(
-     *      path="/user/search/{query}",
+     *      path="/user/search/{?query}",
      *      operationId="searchUsers",
      *      tags={"User"},
      *      summary="Get paginated statuses for single user",
      *      description="Returns paginated statuses of a single user specified by the username",
      *      @OA\Parameter (
      *           name="query",
      *           in="path",
-     *           description="username",
+     *           description="If this is given, the search will be performed on the username and (display)name (or-search)",
      *           example="Gertrud123",
      *      ),
      *      @OA\Parameter (
@@ -453,6 +453,16 @@ public function destroyMute(int $userId): JsonResponse {
      *          in="query",
      *          @OA\Schema(type="integer")
      *      ),
+     *      @OA\Parameter (
+     *          name="username",
+     *          in="query",
+     *          description="Search for parts username",
+     *      ),
+     *      @OA\Parameter (
+     *          name="name",
+     *          in="query",
+     *          description="Search for parts of users (display)name",
+     *      ),
      *      @OA\Response(
      *          response=200,
      *          description="successful operation",
@@ -473,9 +483,33 @@ public function destroyMute(int $userId): JsonResponse {
      *     )
      *
      */
-    public function search(string $query): AnonymousResourceCollection|JsonResponse {
+    public function search(Request $request, ?string $query = null): AnonymousResourceCollection|JsonResponse {
         try {
-            return UserResource::collection(BackendUserBackend::searchUser($query));
+            $validated = $request->validate([
+                                                'username' => ['nullable', 'string', 'max:255'],
+                                                'name'     => ['nullable', 'string', 'max:255'],
+                                            ]);
+            if (empty($validated) && isset($query)) {
+                // if no specific search criteria is given, search for the query in username and display_name
+                return UserResource::collection(BackendUserBackend::searchUser($query));
+            }
+
+            if (empty($validated)) {
+                return response()->json(null, 400);
+            }
+
+            $users = User::query();
+
+            if (isset($validated['username'])) {
+                $users->where('username', 'like', "%{$validated['username']}%");
+            }
+
+            if (isset($validated['name'])) {
+                $users->where('name', 'like', "%{$validated['name']}%");
+            }
+
+            return UserResource::collection($users->simplePaginate(10));
+
         } catch (InvalidArgumentException) {
             return $this->sendError(['message' => __('messages.exception.general')], 400);
         }

routes/api.php

@@ -113,17 +113,17 @@
                 Route::delete('/{userId}/follow', [FollowController::class, 'destroyFollow']);
             });
             Route::group(['middleware' => ['scope:write-followers']], static function() {
-                Route::delete('removeFollower', [FollowController::class, 'removeFollower']); // TODO remove after 2024-10
+                Route::delete('removeFollower', [FollowController::class, 'removeFollower']);           // TODO remove after 2024-10
                 Route::delete('rejectFollowRequest', [FollowController::class, 'rejectFollowRequest']); // TODO remove after 2024-10
-                Route::put('approveFollowRequest', [FollowController::class, 'approveFollowRequest']); // TODO remove after 2024-10
+                Route::put('approveFollowRequest', [FollowController::class, 'approveFollowRequest']);  // TODO remove after 2024-10
             });
             Route::group(['middleware' => ['scope:write-blocks']], static function() {
                 Route::post('/{userId}/block', [UserController::class, 'createBlock']);
                 Route::delete('/{userId}/block', [UserController::class, 'destroyBlock']);
                 Route::post('/{userId}/mute', [UserController::class, 'createMute']);
                 Route::delete('/{userId}/mute', [UserController::class, 'destroyMute']);
             });
-            Route::get('search/{query}', [UserController::class, 'search'])->middleware(['scope:read-search']);
+            Route::get('search/{query?}', [UserController::class, 'search'])->middleware(['scope:read-search']);
             Route::get('statuses/active', [StatusController::class, 'getActiveStatus'])
                  ->middleware(['scope:read-statuses']);
         });
@@ -160,9 +160,9 @@
                 Route::delete('token', [TokenController::class, 'revokeToken']);            //TODO: undocumented endpoint - document when stable
             });
             Route::group(['middleware' => ['scope:read-settings-followers']], static function() {
-                Route::get('followers', [FollowController::class, 'getFollowers']); // TODO remove after 2024-10
+                Route::get('followers', [FollowController::class, 'getFollowers']);            // TODO remove after 2024-10
                 Route::get('follow-requests', [FollowController::class, 'getFollowRequests']); // TODO remove after 2024-10
-                Route::get('followings', [FollowController::class, 'getFollowings']); // TODO remove after 2024-10
+                Route::get('followings', [FollowController::class, 'getFollowings']);          // TODO remove after 2024-10
             });
         });
         Route::group(['prefix' => 'webhooks'], static function() {

storage/api-docs/api-docs.json

@@ -4359,7 +4359,7 @@
                 ]
             }
         },
-        "/user/search/{query}": {
+        "/user/search/{?query}": {
             "get": {
                 "tags": [
                     "User"
@@ -4371,7 +4371,7 @@
                     {
                         "name": "query",
                         "in": "path",
-                        "description": "username",
+                        "description": "If this is given, the search will be performed on the username and (display)name (or-search)",
                         "example": "Gertrud123"
                     },
                     {
@@ -4382,6 +4382,16 @@
                         "schema": {
                             "type": "integer"
                         }
+                    },
+                    {
+                        "name": "username",
+                        "in": "query",
+                        "description": "Search for Username"
+                    },
+                    {
+                        "name": "name",
+                        "in": "query",
+                        "description": "Search for parts of users (display)name"
                     }
                 ],
                 "responses": {

tests/Feature/APIv1/UserSearchTest.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Tests\Feature\APIv1;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Laravel\Passport\Passport;
+use Tests\ApiTestCase;
+
+class UserSearchTest extends ApiTestCase
+{
+
+    use RefreshDatabase;
+
+    public function testUserSearch(): void {
+        $alice   = User::factory(['name' => 'Alice', 'username' => 'alice'])->create();
+        $bob     = User::factory(['name' => 'Bob', 'username' => 'bob'])->create();
+        $charlie = User::factory(['name' => 'Charlie', 'username' => 'charlie'])->create();
+
+        Passport::actingAs($alice, ['*']);
+
+        // 1. Test Search in Path (username AND displayname) - legacy
+        $response = $this->getJson('/api/v1/user/search/charlie');
+        $response->assertOk();
+        $response->assertJsonCount(1, 'data');
+        $response->assertJsonFragment(['id' => $charlie->id]);
+
+        // 2. Test Search for username in query
+        $response = $this->getJson('/api/v1/user/search?username=Charlie');
+        $response->assertOk();
+        $response->assertJsonCount(1, 'data');
+        $response->assertJsonFragment(['id' => $charlie->id]);
+
+        // 3. Test Search for displayname in query
+        $response = $this->getJson('/api/v1/user/search?name=charlie');
+        $response->assertOk();
+        $response->assertJsonCount(1, 'data');
+        $response->assertJsonFragment(['id' => $charlie->id]);
+
+        // 4. Test without any parameters (should fail)
+        $response = $this->getJson('/api/v1/user/search');
+        $response->assertBadRequest();
+    }
+}