Aded roles API controller methods

Altered & updated permissions repo, and existing connected
RoleController to suit.
Also extracts in-app success notifications to auto activity system.
Tweaked tests where required.

app/Http/Controllers/Api/ApiController.php

@@ -32,10 +32,15 @@ abstract class ApiController extends Controller
      */
     public function getValidationRules(): array
     {
-        if (method_exists($this, 'rules')) {
-            return $this->rules();
-        }
+        return $this->rules();
+    }
 
+    /**
+     * Get the validation rules for the actions in this controller.
+     * Defaults to a $rules property but can be a rules() method.
+     */
+    protected function rules(): array
+    {
         return $this->rules;
     }
 }

app/Http/Controllers/Api/RoleApiController.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace BookStack\Http\Controllers\Api;
+
+use BookStack\Auth\Permissions\PermissionsRepo;
+use BookStack\Auth\Role;
+use BookStack\Exceptions\UserUpdateException;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+
+class RoleApiController extends ApiController
+{
+    protected PermissionsRepo $permissionsRepo;
+
+    protected array $fieldsToExpose = [
+        'display_name', 'description', 'mfa_enforced', 'external_auth_id', 'created_at', 'updated_at',
+    ];
+
+    protected $rules = [
+        'create' => [
+            'display_name'  => ['required', 'min:3', 'max:180'],
+            'description'   => ['max:180'],
+            'mfa_enforced'  => ['boolean'],
+            'external_auth_id' => ['string'],
+            'permissions'   => ['array'],
+            'permissions.*' => ['string'],
+        ],
+        'update' => [
+            'display_name'  => ['min:3', 'max:180'],
+            'description'   => ['max:180'],
+            'mfa_enforced'  => ['boolean'],
+            'external_auth_id' => ['string'],
+            'permissions'   => ['array'],
+            'permissions.*' => ['string'],
+        ]
+    ];
+
+    public function __construct(PermissionsRepo $permissionsRepo)
+    {
+        $this->permissionsRepo = $permissionsRepo;
+
+        // Checks for all endpoints in this controller
+        $this->middleware(function ($request, $next) {
+            $this->checkPermission('user-roles-manage');
+
+            return $next($request);
+        });
+    }
+
+    /**
+     * Get a listing of roles in the system.
+     * Requires permission to manage roles.
+     */
+    public function list()
+    {
+        $roles = Role::query()->select(['*'])
+            ->withCount(['users', 'permissions']);
+
+        return $this->apiListingResponse($roles, [
+            ...$this->fieldsToExpose,
+            'permissions_count',
+            'users_count',
+        ]);
+    }
+
+    /**
+     * Create a new role in the system.
+     * Requires permission to manage roles.
+     */
+    public function create(Request $request)
+    {
+        $data = $this->validate($request, $this->rules()['create']);
+
+        $role = null;
+        DB::transaction(function () use ($data, &$role) {
+            $role = $this->permissionsRepo->saveNewRole($data);
+        });
+
+        $this->singleFormatter($role);
+
+        return response()->json($role);
+    }
+
+    /**
+     * View the details of a single user.
+     * Requires permission to manage roles.
+     */
+    public function read(string $id)
+    {
+        $user = $this->permissionsRepo->getRoleById($id);
+        $this->singleFormatter($user);
+
+        return response()->json($user);
+    }
+
+    /**
+     * Update an existing role in the system.
+     * Requires permission to manage roles.
+     */
+    public function update(Request $request, string $id)
+    {
+        $data = $this->validate($request, $this->rules()['update']);
+        $role = $this->permissionsRepo->updateRole($id, $data);
+
+        $this->singleFormatter($role);
+
+        return response()->json($role);
+    }
+
+    /**
+     * Delete a user from the system.
+     * Can optionally accept a user id via `migrate_ownership_id` to indicate
+     * who should be the new owner of their related content.
+     * Requires permission to manage roles.
+     */
+    public function delete(string $id)
+    {
+        $this->permissionsRepo->deleteRole(intval($id));
+
+        return response('', 204);
+    }
+
+    /**
+     * Format the given role model for single-result display.
+     */
+    protected function singleFormatter(Role $role)
+    {
+        $role->load('users:id,name,slug');
+        $role->unsetRelation('permissions');
+        $role->setAttribute('permissions', $role->permissions()->pluck('name'));
+        $role->makeVisible(['users', 'permissions']);
+    }
+}

app/Http/Controllers/RoleController.php

@@ -74,13 +74,17 @@ class RoleController extends Controller
     public function store(Request $request)
     {
         $this->checkPermission('user-roles-manage');
-        $this->validate($request, [
+        $data = $this->validate($request, [
             'display_name' => ['required', 'min:3', 'max:180'],
             'description'  => ['max:180'],
+            'external_auth_id' => ['string'],
+            'permissions'  => ['array'],
+            'mfa_enforced' => ['string'],
         ]);
 
-        $this->permissionsRepo->saveNewRole($request->all());
-        $this->showSuccessNotification(trans('settings.role_create_success'));
+        $data['permissions'] = array_keys($data['permissions'] ?? []);
+        $data['mfa_enforced'] = ($data['mfa_enforced'] ?? 'false') === 'true';
+        $this->permissionsRepo->saveNewRole($data);
 
         return redirect('/settings/roles');
     }
@@ -100,19 +104,27 @@ class RoleController extends Controller
 
     /**
      * Updates a user role.
-     *
-     * @throws ValidationException
      */
     public function update(Request $request, string $id)
     {
         $this->checkPermission('user-roles-manage');
-        $this->validate($request, [
+        $data = $this->validate($request, [
             'display_name' => ['required', 'min:3', 'max:180'],
             'description'  => ['max:180'],
+            'external_auth_id' => ['string'],
+            'permissions'  => ['array'],
+            'mfa_enforced' => ['string'],
         ]);
 
-        $this->permissionsRepo->updateRole($id, $request->all());
-        $this->showSuccessNotification(trans('settings.role_update_success'));
+        if (isset($data['permissions'])) {
+            $data['permissions'] = array_keys($data['permissions']);
+        }
+
+        if (isset($data['mfa_enforced'])) {
+            $data['mfa_enforced'] = $data['mfa_enforced'] === 'true';
+        }
+
+        $this->permissionsRepo->updateRole($id, $data);
 
         return redirect('/settings/roles');
     }
@@ -145,15 +157,13 @@ class RoleController extends Controller
         $this->checkPermission('user-roles-manage');
 
         try {
-            $this->permissionsRepo->deleteRole($id, $request->get('migrate_role_id'));
+            $this->permissionsRepo->deleteRole($id, $request->get('migrate_role_id', 0));
         } catch (PermissionsException $e) {
             $this->showErrorNotification($e->getMessage());
 
             return redirect()->back();
         }
 
-        $this->showSuccessNotification(trans('settings.role_delete_success'));
-
         return redirect('/settings/roles');
     }
 }