Download the PHP package webafra/laravel-permission-mongodb without Composer

laravel-permission-mongodb

This package allows you to manage user permissions and roles in a database. It is inspired from [laravel-permission][link-laravel-permission]. Same code same every thing but it is compatible with [laravel-mongodb][link-laravel-mongodb]

Once installed you can do stuff like this:

If you're using multiple guards we've got you covered as well. Every guard will have its own set of permissions and roles that can be assigned to the guard's users. Read about it in the using multiple guards section of the readme.

Because all permissions will be registered on Laravel's gate, you can test if a user has a permission with Laravel's default can function:

Table of contents

• Installation
  • Laravel Compatibility
  • Laravel
  • Lumen
• Usage
  • Using "direct" permissions
  • Using permissions via roles
  • Using Blade directives
• Using multiple guards
  • Using permissions and roles with multiple guards
  • Assigning permissions and roles to guard users
  • Using blade directives with multiple guards
• Using a middleware
• Using artisan commands
• Unit Testing
• Database Seeding
• Extending
• Cache
  • Manual cache reset
  • Cache Identifier
• Need a UI?
• Change log
• Testing
• Contributing
• Security
• Credits
• License

Installation

Laravel Compatibility

Laravel

You can install the package via composer:

For laravel 9.x use

For laravel 8.x and older use

You can publish the migration with:

You can publish the config file with:

When published, the config/permission.php config file contains:

Lumen

You can install the package via Composer:

Copy the required files:

You will also need to create another configuration file at config/auth.php. Get it on the Laravel repository or just run the following command:

Then, in bootstrap/app.php, register the middlewares:

As well as the configuration and the service provider:

Now, run your migrations:

Usage

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

Note: that if you need to use HasRoles trait with another model ex.Page you will also need to add protected $guard_name = 'web'; as well to that model or you would get an error

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 Moloquent models. They require a name and can be created like this:

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

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

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

If you're using multiple guards the guard_name attribute needs to be set as well. Read about it in the using multiple guards section of the readme.

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

The HasRoles trait also adds a role scope to your models to scope the query to certain roles or permissions:

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

Using "direct" permissions

A permission can be given to any user with the HasRoles trait:

A permission can be revoked from a user:

Or revoke & add new permissions in one go:

You can test if a user has a permission:

...or if a user has multiple permissions:

Saved permissions will be registered with the Illuminate\Auth\Access\Gate class for the default guard. So you can test if a user has a permission with Laravel's default can function:

Using permissions via roles

A role can be assigned to any user:

A role can be removed from a user:

Roles can also be synced:

You can determine if a user has a certain role:

You can also determine if a user has any of a given list of roles:

You can also determine if a user has all of a given list of roles:

The assignRole, hasRole, hasAnyRole, hasAllRoles and removeRole functions can accept a string, a \Webafra\Permission\Models\Role object or an \Illuminate\Support\Collection object.

A permission can be given to a role:

You can determine if a role has a certain permission:

A permission can be revoked from a role:

The givePermissionTo and revokePermissionTo functions can accept a string or a Webafra\Permission\Models\Permission object.

Permissions are inherited from roles automatically. Additionally, individual permissions can be assigned to the user too.

For instance:

In the above example, a role is given permission to edit articles and this role is assigned to a user. Now the user can edit articles and additionally delete articles. The permission of delete articles is the user's direct permission because it is assigned directly to them. When we call $user->hasDirectPermission('delete articles') it returns true, but false for $user->hasDirectPermission('edit articles').

This method is useful if one builds a form for setting permissions for roles and users in an application and wants to restrict or change inherited permissions of roles of the user, i.e. allowing to change only direct permissions of the user.

You can list all of these permissions:

All these responses are collections of Webafra\Permission\Models\Permission objects.

If we follow the previous example, the first response will be a collection with the delete article permission, the second will be a collection with the edit article permission and the third will contain both.

Using Blade directives

This package also adds Blade directives to verify whether the currently logged in user has all or any of a given list of roles.

Optionally you can pass in the guard that the check will be performed on as a second argument.

Blade and Roles

Test for a specific role:

is the same as

Test for any role in a list:

Test for all roles:

Blade and Permissions

This package doesn't add any permission-specific Blade directives. Instead, use Laravel's native @can directive to check if a user has a certain permission.

or

Using multiple guards

When using the default Laravel auth configuration all of the above methods will work out of the box, no extra configuration required.

However when using multiple guards they will act like namespaces for your permissions and roles. Meaning every guard has its own set of permissions and roles that can be assigned to their user model.

Using permissions and roles with multiple guards

When creating new permissions and roles, if no guard is specified, then the first defined guard in auth.guards config array will be used. When creating permissions and roles for specific guards you'll have to specify their guard_name on the model:

Note: When determining whether a role/permission is valid on a given model, it chooses the guard in this order: first the $guard_name property of the model; then the guard in the config (through a provider); then the first-defined guard in the auth.guards config array; then the auth.defaults.guard config.

Assigning permissions and roles to guard users

You can use the same methods to assign permissions and roles to users as described above in using permissions via roles. Just make sure the guard_name on the permission or role matches the guard of the user, otherwise a GuardDoesNotMatch exception will be thrown.

Using blade directives with multiple guards

You can use all of the blade directives listed in using blade directives by passing in the guard you wish to use as the second argument to the directive:

Using a middleware

This package comes with RoleMiddleware and PermissionMiddleware middleware. You can add them inside your app/Http/Kernel.php file.

Then you can protect your routes using middleware rules:

You can protect your controllers similarly, by setting desired middleware in the constructor:

You can add something in Laravel exception handler:

Using artisan commands

You can create a role or permission from a console with artisan commands.

When creating permissions and roles for specific guards you can specify the guard names as a second argument:

Unit Testing

In your application's tests, if you are not seeding roles and permissions as part of your test setUp() then you may run into a chicken/egg situation where roles and permissions aren't registered with the gate (because your tests create them after that gate registration is done). Working around this is simple: In your tests simply add a setUp() instruction to re-register the permissions, like this:

Database Seeding

Two notes about Database Seeding:

1. It is best to flush the webafra.permission.cache before seeding, to avoid cache conflict errors. This can be done from an Artisan command (see Troubleshooting: Cache section, later) or directly in a seeder class (see example below).

2. Here's a sample seeder, which clears the cache, creates permissions, and then assigns permissions to roles:

Extending

If you need to EXTEND the existing Role or Permission models note that:

• Your Role model needs to extend the Webafra\Permission\Models\Role model
• Your Permission model needs to extend the Webafra\Permission\Models\Permission model

If you need to extend or replace the existing Role or Permission models you just need to keep the following things in mind:

• Your Role model needs to implement the Webafra\Permission\Contracts\Role contract
• Your Permission model needs to implement the Webafra\Permission\Contracts\Permission contract

In BOTH cases, whether extending or replacing, you will need to specify your new models in the configuration. To do this you must update the models.role and models.permission values in the configuration file after publishing the configuration with this command:

Cache

Role and Permission data are cached to speed up performance.

When you use the supplied methods for manipulating roles and permissions, the cache is automatically reset for you:

HOWEVER, if you manipulate permission/role data directly in the database instead of calling the supplied methods, then you will not see the changes reflected in the application unless you manually reset the cache.

Manual cache reset

To manually reset the cache for this package, run:

Cache Identifier

Note: If you are leveraging a caching service such as redis or memcached and there are other sites running on your server, you could run into cache clashes. It is prudent to set your own cache prefix in /config/cache.php for each application uniquely. This will prevent other applications from accidentally using/changing your cached data.

Need a UI?

As we are based on [laravel-permission][link-laravel-permission]. The package doesn't come with any screens out of the box, you should build that yourself. To get started check out this extensive tutorial by Caleb Oki.

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

Contributing

Please see CONDUCT for details.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

• [Mostafa MAN][link-author]
• [All Contributors][link-contributors]

License

The MIT License (MIT). Please see License File for more information.