BookStack Code Mirror - bookstack/blob - app/Auth/Role.php

   1 <?php
   2
   3 namespace BookStack\Auth;
   4
   5 use BookStack\Auth\Permissions\EntityPermission;
   6 use BookStack\Auth\Permissions\JointPermission;
   7 use BookStack\Auth\Permissions\RolePermission;
   8 use BookStack\Interfaces\Loggable;
   9 use BookStack\Model;
  10 use Illuminate\Database\Eloquent\Collection;
  11 use Illuminate\Database\Eloquent\Factories\HasFactory;
  12 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
  13 use Illuminate\Database\Eloquent\Relations\HasMany;
  14
  15 /**
  16  * Class Role.
  17  *
  18  * @property int        $id
  19  * @property string     $display_name
  20  * @property string     $description
  21  * @property string     $external_auth_id
  22  * @property string     $system_name
  23  * @property bool       $mfa_enforced
  24  * @property Collection $users
  25  */
  26 class Role extends Model implements Loggable
  27 {
  28     use HasFactory;
  29
  30     protected $fillable = ['display_name', 'description', 'external_auth_id'];
  31
  32     protected $hidden = ['pivot'];
  33
  34     /**
  35      * The roles that belong to the role.
  36      */
  37     public function users(): BelongsToMany
  38     {
  39         return $this->belongsToMany(User::class)->orderBy('name', 'asc');
  40     }
  41
  42     /**
  43      * Get all related JointPermissions.
  44      */
  45     public function jointPermissions(): HasMany
  46     {
  47         return $this->hasMany(JointPermission::class);
  48     }
  49
  50     /**
  51      * The RolePermissions that belong to the role.
  52      */
  53     public function permissions(): BelongsToMany
  54     {
  55         return $this->belongsToMany(RolePermission::class, 'permission_role', 'role_id', 'permission_id');
  56     }
  57
  58     /**
  59      * Get the entity permissions assigned to this role.
  60      */
  61     public function entityPermissions(): HasMany
  62     {
  63         return $this->hasMany(EntityPermission::class);
  64     }
  65
  66     /**
  67      * Check if this role has a permission.
  68      */
  69     public function hasPermission(string $permissionName): bool
  70     {
  71         $permissions = $this->getRelationValue('permissions');
  72         foreach ($permissions as $permission) {
  73             if ($permission->getRawAttribute('name') === $permissionName) {
  74                 return true;
  75             }
  76         }
  77
  78         return false;
  79     }
  80
  81     /**
  82      * Add a permission to this role.
  83      */
  84     public function attachPermission(RolePermission $permission)
  85     {
  86         $this->permissions()->attach($permission->id);
  87     }
  88
  89     /**
  90      * Detach a single permission from this role.
  91      */
  92     public function detachPermission(RolePermission $permission)
  93     {
  94         $this->permissions()->detach([$permission->id]);
  95     }
  96
  97     /**
  98      * Get the role of the specified display name.
  99      */
 100     public static function getRole(string $displayName): ?self
 101     {
 102         return static::query()->where('display_name', '=', $displayName)->first();
 103     }
 104
 105     /**
 106      * Get the role object for the specified system role.
 107      */
 108     public static function getSystemRole(string $systemName): ?self
 109     {
 110         return static::query()->where('system_name', '=', $systemName)->first();
 111     }
 112
 113     /**
 114      * Get all visible roles.
 115      */
 116     public static function visible(): Collection
 117     {
 118         return static::query()->where('hidden', '=', false)->orderBy('name')->get();
 119     }
 120
 121     /**
 122      * Get the roles that can be restricted.
 123      */
 124     public static function restrictable(): Collection
 125     {
 126         return static::query()
 127             ->where('system_name', '!=', 'admin')
 128             ->orderBy('display_name', 'asc')
 129             ->get();
 130     }
 131
 132     /**
 133      * Get a role to represent the case of 'Everyone else' in the system.
 134      * Used within the interface since the default-fallback for permissions uses role_id=0.
 135      */
 136     public static function getEveryoneElseRole(): self
 137     {
 138         return (new static())->forceFill([
 139             'id' => 0,
 140             'display_name' => 'Everyone Else',
 141             'description'  => 'Set permissions for all roles not specifically overridden.'
 142         ]);
 143     }
 144
 145     /**
 146      * {@inheritdoc}
 147      */
 148     public function logDescriptor(): string
 149     {
 150         return "({$this->id}) {$this->display_name}";
 151     }
 152 }