mostafamaklad/laravel-permission-mongodb

为Laravel 5.2及以上版本使用mongodb进行权限处理

维护者

详细信息

github.com/mostafamaklad/laravel-permission-mongodb

主页

源代码

问题

安装: 178,040

依赖: 1

建议者: 0

安全: 0

星标: 111

关注者: 5

分支: 64

开放问题: 15

v5.0.0-alpha 2022-07-01 15:09 UTC

Requires

Requires (Dev)

MIT 7ccc2625ba871263b465a951f5003edf5d9069fa

mongodbsecurityacllaravelpermissionspatiejenssegersMakladmostafamakladmostafa

This package is auto-updated.

Last update: 2024-09-20 09:41:54 UTC

README

ReadMeSupportPalestine

laravel-permission-mongodb

Latest Version on Packagist Software License Build Status Scrutinizer Maintainability Codacy Badge StyleCI Coverage Status Total Downloads StandWithPalestine

此包允许您在数据库中管理用户权限和角色。它受到了laravel-permission的启发。相同的代码，但与laravel-mongodb兼容

安装后，您可以进行如下操作

// Adding permissions to a user
$user->givePermissionTo('edit articles');

// Adding permissions via a role
$user->assignRole('writer');

$role->givePermissionTo('edit articles');

如果您使用多个守卫，我们也为您提供了支持。每个守卫都将拥有自己的权限和角色集合，可以分配给守卫的用户。请阅读readme中的使用多个守卫部分。

由于所有权限都将注册在Laravel的gate上，因此您可以使用Laravel的默认can函数测试用户是否具有权限

$user->can('edit articles');

目录

安装

Laravel 兼容性

Laravel

您可以通过Composer安装此包

对于laravel 9.x使用

composer require mostafamaklad/laravel-permission-mongodb

对于laravel 8.x和更早版本使用

composer require mostafamaklad/laravel-permission-mongodb:"^3.1"

您可以使用以下命令发布迁移

php artisan vendor:publish --provider="Maklad\Permission\PermissionServiceProvider" --tag="migrations"
php artisan migrate

您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Maklad\Permission\PermissionServiceProvider" --tag="config"

发布后，config/permission.php配置文件包含以下内容

return [

    'models' => [

        /*
         * When using the "HasRoles" trait from this package, we need to know which
         * Moloquent model should be used to retrieve your permissions. Of course, it
         * is often just the "Permission" model but you may use whatever you like.
         *
         * The model you want to use as a Permission model needs to implement the
         * `Maklad\Permission\Contracts\Permission` contract.
         */

        'permission' => Maklad\Permission\Models\Permission::class,

        /*
         * When using the "HasRoles" trait from this package, we need to know which
         * Moloquent model should be used to retrieve your roles. Of course, it
         * is often just the "Role" model but you may use whatever you like.
         *
         * The model you want to use as a Role model needs to implement the
         * `Maklad\Permission\Contracts\Role` contract.
         */

        'role' => Maklad\Permission\Models\Role::class,

    ],

    'collection_names' => [

        /*
         * When using the "HasRoles" trait from this package, we need to know which
         * table should be used to retrieve your roles. We have chosen a basic
         * default value but you may easily change it to any table you like.
         */

        'roles' => 'roles',

        /*
         * When using the "HasRoles" trait from this package, we need to know which
         * table should be used to retrieve your permissions. We have chosen a basic
         * default value but you may easily change it to any table you like.
         */

        'permissions' => 'permissions',
    ],

    /*
     * By default all permissions will be cached for 24 hours unless a permission or
     * role is updated. Then the cache will be flushed immediately.
     */

    'cache_expiration_time' => 60 * 24,

    /*
     * By default we'll make an entry in the application log when the permissions
     * could not be loaded. Normally this only occurs while installing the packages.
     *
     * If for some reason you want to disable that logging, set this value to false.
     */

    'log_registration_exception' => true,
    
    /*
     * When set to true, the required permission/role names are added to the exception
     * message. This could be considered an information leak in some contexts, so
     * the default setting is false here for optimum safety.
     */
    
    'display_permission_in_exception' => false,
];

Lumen

您可以通过Composer安装此包

composer require mostafamaklad/laravel-permission-mongodb

复制所需文件

cp vendor/mostafamaklad/laravel-permission-mongodb/config/permission.php config/permission.php
cp vendor/mostafamaklad/laravel-permission-mongodb/database/migrations/create_permission_collections.php.stub database/migrations/2018_01_01_000000_create_permission_collections.php

您还需要在config/auth.php中创建另一个配置文件。从Laravel仓库获取或运行以下命令

curl -Ls https://raw.githubusercontent.com/laravel/lumen-framework/5.5/config/auth.php -o config/auth.php

然后，在bootstrap/app.php中注册中间件

$app->routeMiddleware([
    'auth'       => App\Http\Middleware\Authenticate::class,
    'permission' => Maklad\Permission\Middlewares\PermissionMiddleware::class,
    'role'       => Maklad\Permission\Middlewares\RoleMiddleware::class,
]);

以及配置和服务提供者

$app->configure('permission');
$app->register(Maklad\Permission\PermissionServiceProvider::class);

现在，运行您的迁移

php artisan migrate

使用

首先，将Maklad\Permission\Traits\HasRoles特质添加到您的User模型中

use Illuminate\Auth\Authenticatable;
use Jenssegers\Mongodb\Eloquent\Model as Model;
use Illuminate\Foundation\Auth\Access\Authorizable;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Contracts\Auth\Access\Authorizable as AuthorizableContract;
use Maklad\Permission\Traits\HasRoles;

class User extends Model implements AuthenticatableContract, AuthorizableContract
{
    use Authenticatable, Authorizable, HasRoles;

    // ...
}

注意：如果您需要在其他模型（例如Page）中使用HasRoles特质，您也需要将protected $guard_name = 'web';添加到该模型中，否则您将遇到错误

use Jenssegers\Mongodb\Eloquent\Model as Model;
use Maklad\Permission\Traits\HasRoles;

class Page extends Model
{
    use HasRoles;

    protected $guard_name = 'web'; // or whatever guard you want to use

    // ...
}

此包允许用户与权限和角色关联。每个角色都与多个权限相关联。一个Role和一个Permission是常规Moloquent模型。它们需要一个name，可以像这样创建

use Maklad\Permission\Models\Role;
use Maklad\Permission\Models\Permission;

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

您可以使用以下方法之一将权限分配给角色

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

您可以使用以下方法之一将多个权限同步到角色

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

您可以使用以下方法之一从角色中移除权限

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

如果您正在使用多个守卫，则需要设置guard_name属性。在readme的使用多个守卫部分了解相关信息。

HasRoles特质为您的模型添加Moloquent关系，这些关系可以直接访问或用作基础查询。

// get a list of all permissions directly assigned to the user
$permissions = $user->permissions; // Returns a collection

// get all permissions inherited by the user via roles
$permissions = $user->getAllPermissions(); // Returns a collection

// get all permissions names
$permissions = $user->getPermissionNames(); // Returns a collection

// get a collection of all defined roles
$roles = $user->roles->pluck('name'); // Returns a collection

// get all role names
$roles = $user->getRoleNames() // Returns a collection;

HasRoles特质还为您模型的查询添加了一个role作用域，以便将查询范围限定为特定的角色或权限。

$users = User::role('writer')->get(); // Returns only users with the role 'writer'
$users = User::permission('edit articles')->get(); // Returns only users with the permission 'edit articles'

该作用域可以接受一个字符串、一个\Maklad\Permission\Models\Role对象、一个\Maklad\Permission\Models\Permission对象或一个\Illuminate\Support\Collection对象。

使用"直接"权限

可以使用HasRoles特质将权限授予任何用户。

$user->givePermissionTo('edit articles');

// You can also give multiple permission at once
$user->givePermissionTo('edit articles', 'delete articles');

// You may also pass an array
$user->givePermissionTo(['edit articles', 'delete articles']);

可以从用户那里撤销权限。

$user->revokePermissionTo('edit articles');

或者一次性撤销并添加新的权限。

$user->syncPermissions(['edit articles', 'delete articles']);

您可以使用测试来检查用户是否有权限。

$user->hasPermissionTo('edit articles');

...或者检查用户是否有多个权限。

$user->hasAnyPermission(['edit articles', 'publish articles', 'unpublish articles']);

保存的权限将注册到默认守卫的Illuminate\Auth\Access\Gate类中。因此，您可以使用Laravel的默认can函数来测试用户是否有权限。

$user->can('edit articles');

通过角色使用权限

可以将角色分配给任何用户。

$user->assignRole('writer');

// You can also assign multiple roles at once
$user->assignRole('writer', 'admin');
// or as an array
$user->assignRole(['writer', 'admin']);

可以从用户那里移除角色。

$user->removeRole('writer');

角色也可以进行同步。

// All current roles will be removed from the user and replaced by the array given
$user->syncRoles(['writer', 'admin']);

您可以确定用户是否具有某个特定的角色。

$user->hasRole('writer');

您还可以确定用户是否具有给定列表中的任何角色。

$user->hasAnyRole(Role::all());

您还可以确定用户是否具有给定列表中的所有角色。

$user->hasAllRoles(Role::all());

assignRole、hasRole、hasAnyRole、hasAllRoles和removeRole函数可以接受一个字符串、一个\Maklad\Permission\Models\Role对象或一个\Illuminate\Support\Collection对象。

可以将权限授予角色。

$role->givePermissionTo('edit articles');

您可以确定角色是否具有某个特定的权限。

$role->hasPermissionTo('edit articles');

可以从角色中撤销权限。

$role->revokePermissionTo('edit articles');

givePermissionTo和revokePermissionTo函数可以接受一个字符串或一个Maklad\Permission\Models\Permission对象。

权限会自动从角色继承。此外，还可以将单个权限分配给用户。

例如

$role = Role::findByName('writer');
$role->givePermissionTo('edit articles');

$user->assignRole('writer');

$user->givePermissionTo('delete articles');

在上面的示例中，一个角色被赋予了编辑文章的权限，并且这个角色被分配给了用户。现在该用户可以编辑文章，并且还可以删除文章。delete articles权限是用户的直接权限，因为它直接分配给了他们。当我们调用$user->hasDirectPermission('delete articles')时，它返回true，但对于$user->hasDirectPermission('edit articles')则返回false。

此方法在构建用于设置应用程序中角色和用户权限的表单时很有用，如果您只想更改用户的直接权限，则可以限制或更改角色的继承权限。

您可以列出所有这些权限。

// Direct permissions
$user->getDirectPermissions() // Or $user->permissions;

// Permissions inherited from the user's roles
$user->getPermissionsViaRoles();

// All permissions which apply on the user (inherited and direct)
$user->getAllPermissions();

所有这些响应都是Maklad\Permission\Models\Permission对象的集合。

如果我们遵循前面的示例，第一个响应将包含delete article权限的集合，第二个将包含edit article权限的集合，第三个将包含两者。

使用Blade指令

此包还添加了Blade指令来验证当前登录用户是否具有给定列表中的所有或任何角色。

可选地，您可以将要检查的guard作为第二个参数传递。

Blade和角色

测试特定角色

@role('writer')
    I am a writer!
@else
    I am not a writer...
@endrole

与以下相同

@hasrole('writer')
    I am a writer!
@else
    I am not a writer...
@endhasrole

测试列表中的任何角色

@hasanyrole(Role::all())
    I have one or more of these roles!
@else
    I have none of these roles...
@endhasanyrole
// or
@hasanyrole('writer|admin')
    I am either a writer or an admin or both!
@else
    I have none of these roles...
@endhasanyrole

测试所有角色

@hasallroles(Role::all())
    I have all of these roles!
@else
    I do not have all of these roles...
@endhasallroles
// or
@hasallroles('writer|admin')
    I am both a writer and an admin!
@else
    I do not have all of these roles...
@endhasallroles

Blade和权限

此包不添加任何特定于权限的Blade指令。相反，使用Laravel的本地@can指令来检查用户是否有特定的权限。

@can('edit articles')
  //
@endcan

或

@if(auth()->user()->can('edit articles') && $some_other_condition)
  //
@endif

使用多个守卫

当使用默认的Laravel身份验证配置时，所有上述方法都将默认工作，无需额外配置。

然而，当使用多个守卫时，它们将像命名空间一样作用于您的权限和角色。这意味着每个守卫都有其自己的权限和角色集合，可以分配给其用户模型。

使用多个守卫的权限和角色

在创建新的权限和角色时，如果没有指定守卫，则将使用 auth.guards 配置数组中定义的第一个守卫。当为特定守卫创建权限和角色时，您必须在模型上指定它们的 guard_name。

// Create a superadmin role for the admin users

$user->hasPermissionTo('publish articles', 'admin');

注意：在确定特定模型上的角色/权限是否有效时，它将按以下顺序选择守卫：首先检查模型的 $guard_name 属性；然后是配置中的守卫（通过提供者）；接着是 auth.guards 配置数组中定义的第一个守卫；最后是 auth.defaults.guard 配置。

将权限和角色分配给守卫用户

您可以使用上述方法将权限和角色分配给用户，就像在 通过角色使用权限 部分所描述的那样。只需确保权限或角色上的 guard_name 与用户的守卫匹配，否则将抛出 GuardDoesNotMatch 异常。

使用多个守卫的Blade指令

您可以通过将希望使用的守卫作为指令的第二个参数传递来使用所有列出的 blade 指令。

@role('super-admin', 'admin')
    I am a super-admin!
@else
    I am not a super-admin...
@endrole

使用中间件

此软件包包含 RoleMiddleware 和 PermissionMiddleware 中间件。您可以在 app/Http/Kernel.php 文件中添加它们。

protected $routeMiddleware = [
    // ...
    'role' => \Maklad\Permission\Middlewares\RoleMiddleware::class,
    'permission' => \Maklad\Permission\Middlewares\PermissionMiddleware::class,
];

然后您可以使用中间件规则来保护您的路由。

Route::group(['middleware' => ['role:super-admin']], function () {
    //
});

Route::group(['middleware' => ['permission:publish articles']], function () {
    //
});

Route::group(['middleware' => ['role:super-admin','permission:publish articles']], function () {
    //
});

您也可以通过在构造函数中设置所需的中间件以类似的方式保护您的控制器。

public function __construct()
{
    $this->middleware(['role:super-admin','permission:publish articles|edit articles']);
}

您可以在 Laravel 异常处理器中添加一些内容。

public function render($request, Exception $exception)
{
    if ($exception instanceof \Maklad\Permission\Exceptions\UnauthorizedException) {
        // Code here ...
    }

    return parent::render($request, $exception);
}

使用Artisan命令

您可以使用 artisan 命令从控制台创建角色或权限。

php artisan permission:create-role writer
php artisan permission:create-permission 'edit articles'

在为特定守卫创建权限和角色时，您可以将守卫名称作为第二个参数指定。

php artisan permission:create-role writer web
php artisan permission:create-permission 'edit articles' web

单元测试

在您应用程序的测试中，如果您没有在测试的 setUp() 部分中作为部分进行角色和权限的种植，那么您可能会遇到鸡和蛋的情况，即角色和权限没有在门（因为您的测试在门注册之后创建它们）注册。解决这个问题很简单：在测试中，只需添加一个 setUp() 指令来重新注册权限，如下所示

public function setUp()
{
    // first include all the normal setUp operations
    parent::setUp();

    // now re-register all the roles and permissions
    $this->app->make(\Maklad\Permission\PermissionRegistrar::class)->registerPermissions();
}

数据库填充

关于数据库播种的两个注意事项

  1. 最好在播种之前清除 maklad.permission.cache，以避免缓存冲突错误。这可以通过 Artisan 命令（参见后面的故障排除：缓存部分）或直接在播种类中完成（参见下面的示例）。

  2. 以下是一个示例播种器，它清除缓存、创建权限，然后分配权限给角色

use Illuminate\Database\Seeder;
use Maklad\Permission\Models\Role;
use Maklad\Permission\Models\Permission;

class RolesAndPermissionsSeeder extends Seeder
{
    public function run()
    {
        // Reset cached roles and permissions
        app()['cache']->forget('maklad.permission.cache');
        
        // create permissions
        Permission::firstOrCreate(['name' => 'edit articles']);
        Permission::firstOrCreate(['name' => 'delete articles']);
        Permission::firstOrCreate(['name' => 'publish articles']);
        Permission::firstOrCreate(['name' => 'unpublish articles']);
        
        // create roles and assign existing permissions
        $role = Role::firstOrCreate(['name' => 'writer']);
        $role->givePermissionTo('edit articles');
        $role->givePermissionTo('delete articles');
        
        $role = Role::firstOrCreate(['name' => 'admin']);
        $role->givePermissionTo(['publish articles', 'unpublish articles']);
    }
}

扩展

如果您需要扩展现有的 Role 或 Permission 模型，请注意

  • 您的 Role 模型需要扩展 Maklad\Permission\Models\Role 模型
  • 您的 Permission 模型需要扩展 Maklad\Permission\Models\Permission 模型

如果您需要扩展或替换现有的 Role 或 Permission 模型，您只需注意以下事项

  • 您的 Role 模型需要实现 Maklad\Permission\Contracts\Role 合同
  • 您的 Permission 模型需要实现 Maklad\Permission\Contracts\Permission 合同

在两种情况下，无论是扩展还是替换，您都需要在配置中指定您的新模型。为此，您必须在发布配置后更新配置文件中的 models.role 和 models.permission 值

php artisan vendor:publish --provider="Maklad\Permission\PermissionServiceProvider" --tag="config"

缓存

角色和权限数据被缓存以加速性能。

当您使用提供的用于操作角色和权限的方法时，缓存将自动为您重置

$user->assignRole('writer');
$user->removeRole('writer');
$user->syncRoles(params);
$role->givePermissionTo('edit articles');
$role->revokePermissionTo('edit articles');
$role->syncPermissions(params);
$permission->assignRole('writer');
$permission->removeRole('writer');
$permission->syncRoles(params);

但是，如果您在数据库中直接操作权限/角色数据而不是调用提供的方法，那么除非您手动重置缓存，否则您将看不到更改在应用程序中反映出来

手动重置缓存

要手动重置此软件包的缓存，请运行

php artisan cache:forget maklad.permission.cache

缓存标识符

注意：如果您正在使用缓存服务，例如redis或memcached，并且您的服务器上运行着其他网站，您可能会遇到缓存冲突。建议您在/config/cache.php中为每个应用程序单独设置自己的缓存prefix。这样可以防止其他应用程序意外使用/更改您的缓存数据。

需要用户界面吗？

我们基于laravel-permission。该包默认不包含任何界面，您需要自己构建。要开始，请查看这篇详细的教程，作者是Caleb Oki。

变更日志

有关最近更改的详细信息，请参阅变更日志。

测试

composer test

贡献

有关详细信息，请参阅贡献指南和行为准则。

安全

如果您发现任何安全问题，请通过电子邮件dev.mostafa.maklad@gmail.com报告，而不是使用问题跟踪器。

致谢

许可协议

MIT许可（MIT）。有关更多信息，请参阅许可文件。