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

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