BookStack Code Mirror - bookstack/blob - app/Users/Controllers/RoleApiController.php

   1 <?php
   2
   3 namespace BookStack\Users\Controllers;
   4
   5 use BookStack\Http\ApiController;
   6 use BookStack\Permissions\PermissionsRepo;
   7 use BookStack\Users\Models\Role;
   8 use Illuminate\Http\Request;
   9 use Illuminate\Support\Facades\DB;
  10
  11 class RoleApiController extends ApiController
  12 {
  13     protected PermissionsRepo $permissionsRepo;
  14
  15     protected array $fieldsToExpose = [
  16         'display_name', 'description', 'mfa_enforced', 'external_auth_id', 'created_at', 'updated_at',
  17     ];
  18
  19     protected $rules = [
  20         'create' => [
  21             'display_name'  => ['required', 'string', 'min:3', 'max:180'],
  22             'description'   => ['string', 'max:180'],
  23             'mfa_enforced'  => ['boolean'],
  24             'external_auth_id' => ['string'],
  25             'permissions'   => ['array'],
  26             'permissions.*' => ['string'],
  27         ],
  28         'update' => [
  29             'display_name'  => ['string', 'min:3', 'max:180'],
  30             'description'   => ['string', 'max:180'],
  31             'mfa_enforced'  => ['boolean'],
  32             'external_auth_id' => ['string'],
  33             'permissions'   => ['array'],
  34             'permissions.*' => ['string'],
  35         ]
  36     ];
  37
  38     public function __construct(PermissionsRepo $permissionsRepo)
  39     {
  40         $this->permissionsRepo = $permissionsRepo;
  41
  42         // Checks for all endpoints in this controller
  43         $this->middleware(function ($request, $next) {
  44             $this->checkPermission('user-roles-manage');
  45
  46             return $next($request);
  47         });
  48     }
  49
  50     /**
  51      * Get a listing of roles in the system.
  52      * Requires permission to manage roles.
  53      */
  54     public function list()
  55     {
  56         $roles = Role::query()->select(['*'])
  57             ->withCount(['users', 'permissions']);
  58
  59         return $this->apiListingResponse($roles, [
  60             ...$this->fieldsToExpose,
  61             'permissions_count',
  62             'users_count',
  63         ]);
  64     }
  65
  66     /**
  67      * Create a new role in the system.
  68      * Permissions should be provided as an array of permission name strings.
  69      * Requires permission to manage roles.
  70      */
  71     public function create(Request $request)
  72     {
  73         $data = $this->validate($request, $this->rules()['create']);
  74
  75         $role = null;
  76         DB::transaction(function () use ($data, &$role) {
  77             $role = $this->permissionsRepo->saveNewRole($data);
  78         });
  79
  80         $this->singleFormatter($role);
  81
  82         return response()->json($role);
  83     }
  84
  85     /**
  86      * View the details of a single role.
  87      * Provides the permissions and a high-level list of the users assigned.
  88      * Requires permission to manage roles.
  89      */
  90     public function read(string $id)
  91     {
  92         $role = $this->permissionsRepo->getRoleById($id);
  93         $this->singleFormatter($role);
  94
  95         return response()->json($role);
  96     }
  97
  98     /**
  99      * Update an existing role in the system.
 100      * Permissions should be provided as an array of permission name strings.
 101      * An empty "permissions" array would clear granted permissions.
 102      * In many cases, where permissions are changed, you'll want to fetch the existing
 103      * permissions and then modify before providing in your update request.
 104      * Requires permission to manage roles.
 105      */
 106     public function update(Request $request, string $id)
 107     {
 108         $data = $this->validate($request, $this->rules()['update']);
 109         $role = $this->permissionsRepo->updateRole($id, $data);
 110
 111         $this->singleFormatter($role);
 112
 113         return response()->json($role);
 114     }
 115
 116     /**
 117      * Delete a role from the system.
 118      * Requires permission to manage roles.
 119      */
 120     public function delete(string $id)
 121     {
 122         $this->permissionsRepo->deleteRole(intval($id));
 123
 124         return response('', 204);
 125     }
 126
 127     /**
 128      * Format the given role model for single-result display.
 129      */
 130     protected function singleFormatter(Role $role)
 131     {
 132         $role->load('users:id,name,slug');
 133         $role->unsetRelation('permissions');
 134         $role->setAttribute('permissions', $role->permissions()->orderBy('name', 'asc')->pluck('name'));
 135         $role->makeVisible(['users', 'permissions']);
 136     }
 137 }