Refactored existing user API work

- Updated routes to use new format.
- Changed how hidden fields are exposed to be more flexible to different
  use-cases.
- Updated properties available on read/list results.
- Started adding testing coverage.
- Removed old unused UserRepo 'getAllUsers' function.

Related to #2701, Progression of #2734

app/Http/Controllers/Api/ApiController.php

@@ -10,15 +10,19 @@ use Illuminate\Http\JsonResponse;
 abstract class ApiController extends Controller
 {
     protected $rules = [];
-    protected $printHidden = [];
+    protected $fieldsToExpose = [];
 
     /**
      * Provide a paginated listing JSON response in a standard format
      * taking into account any pagination parameters passed by the user.
      */
-    protected function apiListingResponse(Builder $query, array $fields, array $protectedFieldsToPrint = []): JsonResponse
+    protected function apiListingResponse(Builder $query, array $fields, array $modifiers = []): JsonResponse
     {
-        $listing = new ListingResponseBuilder($query, request(), $fields, $protectedFieldsToPrint);
+        $listing = new ListingResponseBuilder($query, request(), $fields);
+
+        foreach ($modifiers as $modifier) {
+            $listing->modifyResults($modifier);
+        }
 
         return $listing->toResponse();
     }

app/Http/Controllers/Api/UserApiController.php

@@ -2,60 +2,78 @@
 
 namespace BookStack\Http\Controllers\Api;
 
-use BookStack\Exceptions\PermissionsException;
 use BookStack\Auth\User;
 use BookStack\Auth\UserRepo;
-use Exception;
-use Illuminate\Http\Request;
+use Closure;
 
 class UserApiController extends ApiController
 {
-    protected $user;
     protected $userRepo;
 
-    protected $printHidden = [
-        'email', 'created_at', 'updated_at', 'last_activity_at'
+    protected $fieldsToExpose = [
+        'email', 'created_at', 'updated_at', 'last_activity_at', 'external_auth_id'
     ];
 
-# TBD: Endpoints to create / update users
-#     protected $rules = [
-#         'create' => [
-#         ],
-#         'update' => [
-#         ],
-#     ];
+    protected $rules = [
+        'create' => [
+        ],
+        'update' => [
+        ],
+    ];
 
-    public function __construct(User $user, UserRepo $userRepo)
+    public function __construct(UserRepo $userRepo)
     {
-        $this->user = $user;
         $this->userRepo = $userRepo;
     }
 
     /**
-     * Get a listing of users
+     * Get a listing of users in the system.
+     * Requires permission to manage users.
      */
     public function list()
     {
         $this->checkPermission('users-manage');
 
-        $users = $this->userRepo->getUsersBuilder();
+        $users = $this->userRepo->getApiUsersBuilder();
 
         return $this->apiListingResponse($users, [
-            'id', 'name', 'slug', 'email',
+            'id', 'name', 'slug', 'email', 'external_auth_id',
             'created_at', 'updated_at', 'last_activity_at',
-        ], $this->printHidden);
+        ], [Closure::fromCallable([$this, 'listFormatter'])]);
     }
 
     /**
-     * View the details of a single user
+     * View the details of a single user.
+     * Requires permission to manage users.
      */
     public function read(string $id)
     {
         $this->checkPermission('users-manage');
 
         $singleUser = $this->userRepo->getById($id);
-        $singleUser = $singleUser->makeVisible($this->printHidden);
+        $this->singleFormatter($singleUser);
 
         return response()->json($singleUser);
     }
+
+    /**
+     * Format the given user model for single-result display.
+     */
+    protected function singleFormatter(User $user)
+    {
+        $this->listFormatter($user);
+        $user->load('roles:id,display_name');
+        $user->makeVisible(['roles']);
+    }
+
+    /**
+     * Format the given user model for a listing multi-result display.
+     */
+    protected function listFormatter(User $user)
+    {
+        $user->makeVisible($this->fieldsToExpose);
+        $user->setAttribute('profile_url', $user->getProfileUrl());
+        $user->setAttribute('edit_url', $user->getEditUrl());
+        $user->setAttribute('avatar_url', $user->getAvatar());
+    }
 }