- 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
namespace BookStack\Api;
+use BookStack\Model;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
class ListingResponseBuilder
protected $query;
protected $request;
protected $fields;
- protected $hiddenFields;
+
+ /**
+ * @var array<callable>
+ */
+ protected $resultModifiers = [];
protected $filterOperators = [
'eq' => '=',
/**
* ListingResponseBuilder constructor.
+ * The given fields will be forced visible within the model results.
*/
- public function __construct(Builder $query, Request $request, array $fields, array $hiddenFields )
+ public function __construct(Builder $query, Request $request, array $fields)
{
$this->query = $query;
$this->request = $request;
$this->fields = $fields;
- $this->hiddenFields = $hiddenFields;
}
/**
* Get the response from this builder.
*/
- public function toResponse()
+ public function toResponse(): JsonResponse
{
$filteredQuery = $this->filterQuery($this->query);
$total = $filteredQuery->count();
- $data = $this->fetchData($filteredQuery);
- $data = $data->makeVisible($this->hiddenFields);
+ $data = $this->fetchData($filteredQuery)->each(function($model) {
+ foreach ($this->resultModifiers as $modifier) {
+ $modifier($model);
+ }
+ });
return response()->json([
'data' => $data,
}
/**
- * Fetch the data to return in the response.
+ * Add a callback to modify each element of the results
+ * @param (callable(Model)) $modifier
+ */
+ public function modifyResults($modifier): void
+ {
+ $this->resultModifiers[] = $modifier;
+ }
+
+ /**
+ * Fetch the data to return within the response.
*/
protected function fetchData(Builder $query): Collection
{
protected $fillable = ['display_name', 'description', 'external_auth_id'];
+ protected $hidden = ['pivot'];
+
/**
* The roles that belong to the role.
*/
*/
protected $hidden = [
'password', 'remember_token', 'system_name', 'email_confirmed', 'external_auth_id', 'email',
- 'created_at', 'updated_at', 'image_id',
+ 'created_at', 'updated_at', 'image_id', 'roles', 'avatar',
];
/**
return User::query()->where('slug', '=', $slug)->firstOrFail();
}
- /**
- * Get all the users with their permissions.
- */
- public function getAllUsers(): Collection
- {
- return User::query()->with('roles', 'avatar')->orderBy('name', 'asc')->get();
- }
-
/**
* Get all users as Builder for API
*/
- public function getUsersBuilder(int $id = null ) : Builder
+ public function getApiUsersBuilder() : Builder
{
- $query = User::query()->select(['*'])
- ->withLastActivityAt()
- ->with(['roles', 'avatar']);
- return $query;
+ return User::query()->select(['*'])
+ ->scopes('withLastActivityAt')
+ ->with(['avatar']);
}
/**
* Get all the users with their permissions in a paginated format.
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();
}
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());
+ }
}
use BookStack\Http\Controllers\Api\PageApiController;
use BookStack\Http\Controllers\Api\PageExportApiController;
use BookStack\Http\Controllers\Api\SearchApiController;
+use BookStack\Http\Controllers\Api\UserApiController;
use Illuminate\Support\Facades\Route;
/**
Route::put('shelves/{id}', [BookshelfApiController::class, 'update']);
Route::delete('shelves/{id}', [BookshelfApiController::class, 'delete']);
-Route::get('users', 'UserApiController@list');
-Route::get('users/{id}', 'UserApiController@read');
\ No newline at end of file
+Route::get('users', [UserApiController::class, 'list']);
+Route::get('users/{id}', [UserApiController::class, 'read']);
\ No newline at end of file
--- /dev/null
+<?php
+
+namespace Tests\Api;
+
+use BookStack\Auth\Role;
+use BookStack\Auth\User;
+use Tests\TestCase;
+
+class UsersApiTest extends TestCase
+{
+ use TestsApi;
+
+ protected $baseEndpoint = '/api/users';
+
+ public function test_users_manage_permission_needed_for_all_endpoints()
+ {
+ // TODO
+ }
+
+ public function test_index_endpoint_returns_expected_shelf()
+ {
+ $this->actingAsApiAdmin();
+ /** @var User $firstUser */
+ $firstUser = User::query()->orderBy('id', 'asc')->first();
+
+ $resp = $this->getJson($this->baseEndpoint . '?count=1&sort=+id');
+ $resp->assertJson(['data' => [
+ [
+ 'id' => $firstUser->id,
+ 'name' => $firstUser->name,
+ 'slug' => $firstUser->slug,
+ 'email' => $firstUser->email,
+ 'profile_url' => $firstUser->getProfileUrl(),
+ 'edit_url' => $firstUser->getEditUrl(),
+ 'avatar_url' => $firstUser->getAvatar(),
+ ],
+ ]]);
+ }
+
+ public function test_read_endpoint()
+ {
+ $this->actingAsApiAdmin();
+ /** @var User $user */
+ $user = User::query()->first();
+ /** @var Role $userRole */
+ $userRole = $user->roles()->first();
+
+ $resp = $this->getJson($this->baseEndpoint . "/{$user->id}");
+
+ $resp->assertStatus(200);
+ $resp->assertJson([
+ 'id' => $user->id,
+ 'slug' => $user->slug,
+ 'email' => $user->email,
+ 'external_auth_id' => $user->external_auth_id,
+ 'roles' => [
+ [
+ 'id' => $userRole->id,
+ 'display_name' => $userRole->display_name,
+ ]
+ ],
+ ]);
+ }
+}
projects / bookstack / commitdiff