Basic Usage | laravel-permission | Spatie

 SPATIE

  Laravel Permission
=====================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-permission](https://spatie.be/docs/laravel-permission/v7)  Basic-usage  Basic Usage

 Version   v7   v6   v5   v4   v3

 Other versions for crawler [v7](https://spatie.be/docs/laravel-permission/v7) [v6](https://spatie.be/docs/laravel-permission/v6) [v5](https://spatie.be/docs/laravel-permission/v5) [v4](https://spatie.be/docs/laravel-permission/v4) [v3](https://spatie.be/docs/laravel-permission/v3)

- [ Introduction ](https://spatie.be/docs/laravel-permission/v7/introduction)
- [ Support us ](https://spatie.be/docs/laravel-permission/v7/support-us)
- [ Prerequisites ](https://spatie.be/docs/laravel-permission/v7/prerequisites)
- [ Installation in Laravel ](https://spatie.be/docs/laravel-permission/v7/installation-laravel)
- [ Upgrading ](https://spatie.be/docs/laravel-permission/v7/upgrading)
- [ Questions and issues ](https://spatie.be/docs/laravel-permission/v7/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-permission/v7/changelog)
- [ About us ](https://spatie.be/docs/laravel-permission/v7/about-us)

Basic Usage
-----------

- [ Basic Usage ](https://spatie.be/docs/laravel-permission/v7/basic-usage/basic-usage)
- [ Direct Permissions ](https://spatie.be/docs/laravel-permission/v7/basic-usage/direct-permissions)
- [ Using Permissions via Roles ](https://spatie.be/docs/laravel-permission/v7/basic-usage/role-permissions)
- [ Enums ](https://spatie.be/docs/laravel-permission/v7/basic-usage/enums)
- [ Teams permissions ](https://spatie.be/docs/laravel-permission/v7/basic-usage/teams-permissions)
- [ Wildcard permissions ](https://spatie.be/docs/laravel-permission/v7/basic-usage/wildcard-permissions)
- [ Blade directives ](https://spatie.be/docs/laravel-permission/v7/basic-usage/blade-directives)
- [ Defining a Super-Admin ](https://spatie.be/docs/laravel-permission/v7/basic-usage/super-admin)
- [ Using multiple guards ](https://spatie.be/docs/laravel-permission/v7/basic-usage/multiple-guards)
- [ Artisan Commands ](https://spatie.be/docs/laravel-permission/v7/basic-usage/artisan)
- [ Middleware ](https://spatie.be/docs/laravel-permission/v7/basic-usage/middleware)
- [ Passport Client Credentials Grant usage ](https://spatie.be/docs/laravel-permission/v7/basic-usage/passport)
- [ Example App ](https://spatie.be/docs/laravel-permission/v7/basic-usage/new-app)

Best Practices
--------------

- [ Roles vs Permissions ](https://spatie.be/docs/laravel-permission/v7/best-practices/roles-vs-permissions)
- [ Model Policies ](https://spatie.be/docs/laravel-permission/v7/best-practices/using-policies)
- [ Performance Tips ](https://spatie.be/docs/laravel-permission/v7/best-practices/performance)

Advanced usage
--------------

- [ Testing ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/testing)
- [ Database Seeding ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/seeding)
- [ Exceptions ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/exceptions)
- [ Extending ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/extending)
- [ Cache ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/cache)
- [ Events ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/events)
- [ Custom Permission Check ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/custom-permission-check)
- [ UUID/ULID ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/uuid)
- [ PhpStorm Interaction ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/phpstorm)
- [ Other ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/other)
- [ Timestamps ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/timestamps)
- [ UI Options ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/ui-options)

 Basic Usage
===========

###  On this page

1. [ Add The Trait ](#content-add-the-trait)
2. [ Create A Permission ](#content-create-a-permission)
3. [ Assign A Permission To A Role ](#content-assign-a-permission-to-a-role)
4. [ Sync Permissions To A Role ](#content-sync-permissions-to-a-role)
5. [ Remove Permission From A Role ](#content-remove-permission-from-a-role)
6. [ Guard Name ](#content-guard-name)
7. [ Get Permissions For A User ](#content-get-permissions-for-a-user)
8. [ Scopes ](#content-scopes)
9. [ Eloquent Calls ](#content-eloquent-calls)
10. [ Counting Users Having A Role ](#content-counting-users-having-a-role)

Add The Trait
-----------------------------------------------------------------------------------------------

First, add the `Spatie\Permission\Traits\HasRoles` trait to your `User` model(s):

```
use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;

    // ...
}
```

Create A Permission
-----------------------------------------------------------------------------------------------------------------

This package allows for users to be associated with permissions and roles. Every role is associated with multiple permissions. A `Role` and a `Permission` are regular Eloquent models. They require a `name` and can be created like this:

```
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;

$role = Role::create(['name' => 'writer']);
$permission = Permission::create(['name' => 'edit articles']);
```

Assign A Permission To A Role
-----------------------------------------------------------------------------------------------------------------------------------------------

A permission can be assigned to a role using either of these methods:

```
$role->givePermissionTo($permission);
$permission->assignRole($role);
```

Sync Permissions To A Role
--------------------------------------------------------------------------------------------------------------------------------------

Multiple permissions can be synced to a role using either of these methods:

```
$role->syncPermissions($permissions);
$permission->syncRoles($roles);
```

Remove Permission From A Role
-----------------------------------------------------------------------------------------------------------------------------------------------

A permission can be removed from a role using either of these methods:

```
$role->revokePermissionTo($permission);
$permission->removeRole($role);
```

Guard Name
--------------------------------------------------------------------------------------

If you're using multiple guards then the `guard_name` attribute must be set as well. Read about it in the [using multiple guards](./multiple-guards) documentation.

Get Permissions For A User
--------------------------------------------------------------------------------------------------------------------------------------

The `HasRoles` trait adds Eloquent relationships to your models, which can be accessed directly or used as a base query:

```
// get a list of all permissions directly assigned to the user
$permissionNames = $user->getPermissionNames(); // collection of name strings
$permissions = $user->permissions; // collection of permission objects

// get all permissions for the user, either directly, or from roles, or from both
$permissions = $user->getDirectPermissions();
$permissions = $user->getPermissionsViaRoles();
$permissions = $user->getAllPermissions();

// get the names of the user's roles
$roles = $user->getRoleNames(); // Returns a collection
```

Scopes
--------------------------------------------------------------------------

The `HasRoles` trait also adds `role` and `withoutRole` scopes to your models to scope the query to certain roles or permissions:

```
$users = User::role('writer')->get(); // Returns only users with the role 'writer'
$nonEditors = User::withoutRole('editor')->get(); // Returns only users without the role 'editor'
```

The `role` and `withoutRole` scopes can accept a string, a `\Spatie\Permission\Models\Role` object or an `\Illuminate\Support\Collection` object.

The same trait also adds scopes to only get users that have or don't have a certain permission.

```
$users = User::permission('edit articles')->get(); // Returns only users with the permission 'edit articles' (inherited or directly)
$usersWhoCannotEditArticles = User::withoutPermission('edit articles')->get(); // Returns all users without the permission 'edit articles' (inherited or directly)
```

The scope can accept a string, a `\Spatie\Permission\Models\Permission` object or an `\Illuminate\Support\Collection` object.

Eloquent Calls
--------------------------------------------------------------------------------------------------

Since Role and Permission models are extended from Eloquent models, basic Eloquent calls can be used as well:

```
$allUsersWithAllTheirRoles = User::with('roles')->get();
$allUsersWithAllTheirDirectPermissions = User::with('permissions')->get();
$allRolesInDatabase = Role::all()->pluck('name');
$usersWithoutAnyRoles = User::doesntHave('roles')->get();
$allRolesExceptAandB = Role::whereNotIn('name', ['role A', 'role B'])->get();
```

Counting Users Having A Role
--------------------------------------------------------------------------------------------------------------------------------------------

One way to count all users who have a certain role is by filtering the collection of all Users with their Roles:

```
$managersCount = User::with('roles')->get()->filter(
    fn ($user) => $user->roles->where('name', 'Manager')->toArray()
)->count();
```