README

适用于Laravel 5.8及以上版本的Eloquent角色和权限包。

安装

您可以通过composer安装此包

composer require miracuthbert/laravel-roles

设置

该包利用了Laravel自动发现功能，因此不需要您手动添加ServiceProvider。

如果您不使用自动发现，请在config/app.php中的providers数组中添加ServiceProvider

Miracuthbert\LaravelRoles\LaravelRolesServiceProvider::class

迁移

首先，您需要发布包的迁移文件

php artisan vendor:publish --tag=laravel-roles-migrations

对于之前已发布迁移的用户，使用以下命令来发布更新更改

php artisan vendor:publish --tag=laravel-roles-permitable-migrations

然后运行迁移命令

php artisan migrate

填充

默认情况下，该包包含一个用于角色和权限的填充器RolesAndPermissionsTableSeeder。

您可以将它添加到您的DatabaseSeeder中，或者使用以下命令单独运行它。

php artisan db:seed --class=RolesAndPermissionsTableSeeder

请参阅用法部分，了解如何通过控制台为用户分配角色。

配置

要自定义包的使用，请使用发布命令将包配置复制到本地配置中

php artisan vendor:publish --tag=laravel-roles-config

该包包括以下配置：

角色共享

allow_shared_roles键使包能够查询可由模型共享的角色。

例如，Team模型的一个admin角色可以被应用程序管理员共享和轻松管理，而与可能在不同团队之间变化的manager角色相比。

用户模型

默认用户模型是App\Models\User::class，它是默认的User模型命名空间。

您可以通过在配置文件中更改users下的model键来更改默认用户模型。

请参阅用法部分，了解如何在用户模型上启用角色和权限。

中间件

在中间件下，您可以配置默认为403的abort_code。

可允许的类型

您可以在应用程序内设置允许创建的角色和权限的类型。

在多租户应用程序中，这可以用于过滤基于Admin和Tenant的权限和角色。

例如，如果您的应用程序有teams并且每个成员执行独特任务，您可以在配置文件中的permitables下定义一个权限或角色类型team，这样就可以过滤出仅包含team权限或角色的权限。

'team' => 'Team'

非管理员角色的可允许类型需要在配置文件的模型数组中添加为键以进行链接。

模型

您还可以将上面提到的permitables类型映射到相关模型。

'team' => \App\Models\Team::class

每个模型只能映射到一个可允许类型。

用法

要开始为用户分配角色和权限，您必须首先将LaravelRolesUserTrait特质添加到User模型。

用户模型应与包配置文件中指示的模型相匹配。请参阅配置。

分配角色

基本

要为用户分配角色，您可以在用户模型实例上调用assignRole方法。

assignRole方法接受一个role（角色模型实例），一个可选的日期expiresAt，以及一个可选的Eloquent模型实例giver，该实例在配置中注册。

$user->assignRole($role, $expiresAt, $giver);

expiresAt值必须是一个未来的日期。

当角色分配属于已注册模型时，可以省略giver值。

通过控制台

要使用控制台分配角色，请使用以下命令，传递已注册用户的email和有效的角色slug。

例如，一个电子邮件地址为johndoe@example.org的用户，有一个名为Admin Root的角色，slug为admin-root，将会是

php artisan role:assign johndoe@example.org admin-root

您可以使用与包一起提供的seeder来初始化角色和权限表。请参阅初始化。

撤销角色

撤销角色与分配相同，即在用户模型实例上调用revokeRoleAt方法。

此方法接受一个role（角色模型实例）和expiresAt日期，该日期是可选的。

如果没有提供expiresAt日期，则角色将立即撤销。

$user->revokeRoleAt($role, $expiresAt);

撤销所有角色

要从用户撤销所有角色，请在用户模型实例上调用revokeRoles方法。

此方法接受一个可选的roles数组（或Role模型实例的集合）。

如果没有传递值给方法，则将撤销用户的有效角色。

注意：撤销角色只是设置了过期时间戳，不会删除用户角色的历史记录。

$user->revokeRoles(); 

// with an array of values
$user->revokeRoles(['admin-root', 'admin-basic']);

分离所有角色

要从用户分离所有角色，请在用户模型实例上调用detachRoles方法。

此方法接受一个可选的roles数组（或Role模型实例的集合）。

从用户分离角色将完全删除用户角色的历史记录。

$user->detachRoles(); 

// with an array of values
$user->detachRoles(['admin-root', 'admin-basic']);

授权

您可以使用各种方式使用此包授权用户

角色

要检查用户是否有有效的角色，请使用有效的Role模型的slug。

角色必须是usable（活跃的）。

通过用户模型

if($user->hasRole('admin-root')) {
    // user can do something as admin
}

检查多个角色

if($user->hasRole(['admin-root', 'manager', 'editor'])) {
    // user can do something as admin
}

或

if($user->hasRole('admin-root', 'manager', 'editor')) {
    // user can do something as admin
}

通过Blade辅助函数

@role('admin-root')
    <!-- The user can do root admin stuff -->
@endrole

中间件

您可以使用role中间件来检查用户是否有权限。

它接受一个角色slug和权限slug或name。

在路由中

// Just role
Route::middleware(['role:admin-root'])->get('/admin/logs');

// Via role and permission 
Route::middleware(['role:admin-root,delete-admins'])->delete('/admin/roles/editors/revoke');

在控制器中

public function __construct() {
    // Via permission name `browse admin`
    $this->middleware(['role:admin-root']);
    
    // Via role and permission (slug or name)
    $this->middleware(['role:admin-root,delete-admins']);
}

请参阅权限部分以了解如何通过权限授权用户。

权限

要检查用户是否有权限，请使用有效的Permission模型的slug或name。

例如，一个名为browse admin的权限可以传递为browse-admin或browse admin。

权限必须是usable（活跃的）。

接受一个额外的参数giver，如果您必须根据分配它的模型检查权限。

例如，要检查用户是否通过类型为team的角色拥有权限

• 您可以传递一个Team模型实例
• 或传递一个具有对应id的类型：team:1。

无论id是slug还是基本id，它都将由包解决。

当传递类型时，请确保它具有在包配置中的models键下注册的对应模型。

通过门卫

if(Gate::allows('browse-admin')) {
    // do something
}

// With giver
if(Gate::allows('browse-admin', $team)) {
    // do something
}

if(Gate::denies('browse-admin')) {
    return abort(403);
}

// With giver
if(Gate::denies('browse-admin', $team)) {
    return abort(403);
}

通过用户模型

if($user->can('assign roles')) {
    // do something
}

// With giver
if($user->can('assign roles', $team)) {
    // do something
}

通过Blade辅助函数

@can('impersonate user')
    <!-- The user can impersonate another user -->
@endcan

// With giver
@can('impersonate user', $team)
    <!-- The user can impersonate another user -->
@endcan

@cannot('impersonate user')
    <!-- The user can't impersonate another user -->
@endcannot

// With giver
@cannot('impersonate user', $team)
    <!-- The user can't impersonate another user -->
@endcannot

中间件

使用中间件有两种方式

在路由中

// Via permission name `browse admin`
Route::middleware(['permission: browse admin'])->get('/admin/dashboard');

// Via permission slug `browse-admin`
Route::middleware(['permission: browse-admin'])->get('/admin/dashboard');

在控制器中

public function __construct() {
    // Via permission name `browse admin`
    $this->middleware(['permission: browse admin']);
    
    // Via permission slug `browse-admin`
    $this->middleware(['permission: browse-admin']);

    // Via permission name `browse admin` with giver, the id should be fetched from the request or dynamically resolved
    $this->middleware(['permission: browse admin, team:' . $request->team]);
    
    // Via permission slug `browse-admin` with giver, the id should be fetched from the request or dynamically resolved
    $this->middleware(['permission: browse-admin, team:' . $request->team]);
}

安全漏洞

如果您发现安全漏洞，请通过电子邮件将问题发送给Cuthbert Mirambo（miracuthbert@gmail.com）。所有安全漏洞都将得到及时解决。

致谢

• Cuthbert Mirambo

许可证

此项目是开源软件，许可协议为MIT许可证。