From f9df5903c57f2a026dc56714bc80f157af7d246c Mon Sep 17 00:00:00 2001 From: Tony Lea Date: Tue, 13 Aug 2024 20:14:27 -0400 Subject: [PATCH] Update roles-permissions.md --- content/docs/features/roles-permissions.md | 109 ++++++++++++++++++++- 1 file changed, 107 insertions(+), 2 deletions(-) diff --git a/content/docs/features/roles-permissions.md b/content/docs/features/roles-permissions.md index ffbd665..11629c0 100644 --- a/content/docs/features/roles-permissions.md +++ b/content/docs/features/roles-permissions.md @@ -11,10 +11,13 @@ nextURL: '/docs/features/notifications' Roles and Permissions allow you to manage who can access different parts of your web application. +- [Roles](#roles) +- [Permissions](#permissions) +- [Digging Deeper](#digging-deeper) ## Roles -Roles are labels or titles that you give to users in your web application to define what they can or cannot do. By default, Wave ships with five roles: +Roles are labels that you give to users to define what they can or cannot do. By default, Wave ships with five roles: 1. **Admin** - This is the role you will have as the developer and administrator. 2. **Registerd** - This is the default role for a newly registered user @@ -24,7 +27,7 @@ Roles are labels or titles that you give to users in your web application to def The **Admin** role should not be modified as there are many references to this role in the codebase; however, you may modify any of the other roles. -The **Registered** role is the default role that every user will have when they register for an account with your application. If y ou wish to change the name of this role, make sure that you also modify the `default_user_role` value inside of the `wave.php` config file. +The **Registered** role is the default role that every user will have when they register for an account with your application. If you wish to change the name of this role, make sure that you also modify the `default_user_role` value inside of the `wave.php` config file. Next, you may also modify/delete any of the **Basic**, **Premium**, and **Pro** roles to meet the needs of your application. These roles are associated with a **Subscription Plan**. You'll notice that Wave also ships with a **Basic**, **Premium**, and **Pro** plan. The mindset here is that when a user upgrades or purchases a plan, they will be assigned a role that corresponds to that plan. @@ -32,6 +35,108 @@ Next, you may also modify/delete any of the **Basic**, **Premium**, and **Pro** It’s not mandatory for the user **Role** to have the same name as the **Plan**; however, doing so will make things easier to understand. Additionally, a user doesn’t have to have only one Role; but, keeping it this way will make things easier to comprehend and manage. +### Creating Roles + +You can easily create a role inside of your application from adding it in the admin. Alternatively, you may also create the new permission via code, like so: + +```php +use Spatie\Permission\Models\Role; + +$role = Role::create(['name' => 'writer']); +``` + +This will create a new role named **writer**. + +### Assigning Roles + +You can then assign this role to any user, like so: + +```php +auth()->user()->syncRoles([]); +auth()->user()->assignRole('writer'); +``` + +Above, we are making sure that we remove all roles `syncRoles([])` and then assign the role of **writer**. You may decide to allow users to have multiple roles, which in that case you don't need syncRoles. + +### Getting users with role + +If you want to retrieve a list of all the users who have the **writer** role, you could do so like the following: + +```php +$users = User::role('writer')->get(); +``` + +This will return a collection of all users with the **writer** role. + +### Checking if a user has role + +If you want to check that a user has a specific role, you can do so like the following: + +```php +auth()->user()->hasRole('writer'); +``` + +Or directly from a blade view you can use this blade directive + +```php +@role('writer') + I am a writer! +@else + I am not a writer... +@endrole +``` + +Next, if we wanted to be more granular with which users have access to specific features, we could use permissions. + +## Permissions + +You can create permissions and assign them to users or you can assign them to roles. This will make it easier when you want to create more granular permissions. Let's learn more about how we can use permissions. + +### Creating Permissions + +You can create a permission from the Admin panel, or you may also wish to do this in code: + +```php +use Spatie\Permission\Models\Permission; + +$permission = Permission::create(['name' => 'edit articles']); +``` + +Then, you can assign assign a permission to any role: + +```php +use Spatie\Permission\Models\Role; + +$role = Role::where('name', 'writer')->first(); +``` + +You may also assign a permission specifically to a user: + +```php +auth()->user()->givePermissionTo('edit articles'); +``` + +These are referred to as direct permissions. Make sure that you are careful with adding permissions to roles and specifically to users. It can get a little complex if you don't keep it organized. It might be best to only assign permissions to roles. + +### Revoking Permissions + +The reason that it's better to only assign permissions to roles is that you can easily revoke a permission from a role, like so: + +```php +use Spatie\Permission\Models\Role; +use Spatie\Permission\Models\Permission; + +$role = Role::where('name', 'writer')->first(); +$permission = Permission::were('name', 'edit articles')->first(); + +$role->revokePermissionTo($permission); +``` + +This means that all users of that role will all have that permission removed. You may also revokePermissions from a user. + +### Checking Permissions + +add checking permission docs ## Digging Deeper