README

Cerberus是向Laravel 5.*添加基于角色的权限的灵活方式

内容

• 安装
• 配置
  • 用户与角色之间的关系
  • 模型
    • 角色
    • 权限
    • 用户
    • 软删除
• 使用方法
  • 概念
    • 检查角色和权限
    • 用户能力
  • Blade模板
  • 中间件
• 故障排除
• 许可
• 贡献指南
• 附加信息

安装

1. 运行以下命令安装Laravel 5 Cerberus

composer require michalisantoniou6/cerberus

或者，您可以将以下内容添加到您的composer.json中。然后运行composer update

"michalisantoniou6/cerberus": "2.*"

如果您希望始终获取最新的稳定版本，请要求dev-master。

"michalisantoniou6/cerberus": "dev-master"

1. 打开您的config/app.php，并将以下内容添加到providers数组中。如果您使用的是Laravel 5.5，可以跳过此步骤，因为软件包将自动注册。

Michalisantoniou6\Cerberus\CerberusServiceProvider::class,

1. 如果您想使用Facade，请将以下内容添加到config/app.php中的aliases数组中

'Cerberus'   => Michalisantoniou6\Cerberus\CerberusFacade::class,

1. 运行以下命令发布软件包配置文件config/cerberus.php。在您的配置文件中设置模型和键。

php artisan vendor:publish

1. 如果您想使用中间件（需要Laravel 5.1或更高版本），请将以下内容添加到routeMiddleware数组中

    'role' => \Michalisantoniou6\Cerberus\Middleware\CerberusRole::class,
    'permission' => \Michalisantoniou6\Cerberus\Middleware\CerberusPermission::class,
    'ability' => \Michalisantoniou6\Cerberus\Middleware\CerberusAbility::class,

在app/Http/Kernel.php中。

配置

在config/cerberus.php中设置属性值。这些值将由Cerberus用于引用正确的用户/网站/角色/权限表和模型。

要自定义表名和模型命名空间，请编辑config/cerberus.php。

用户与角色之间的关系

现在生成Cerberus迁移

php artisan cerberus:migration

它将生成<timestamp>_cerberus_setup_tables.php迁移。您可以在迁移中添加其他字段。审查迁移，然后使用artisan migrate命令运行它

php artisan migrate

模型

角色

在app/models/Role.php内部创建一个Role模型，使用以下示例

<?php namespace App;

use Michalisantoniou6\Cerberus\CerberusRole;

class Role extends CerberusRole
{
}

Role模型有三个主要属性

• name — 角色的唯一名称，用于在应用层查找角色信息。例如：“管理员”，“所有者”，“员工”。
• display_name — 角色的人读名称。不一定唯一，可选。例如：“用户管理员”，“项目所有者”，“Widget Co.员工”。
• description — 角色功能的更详细说明。可选。

display_name和description都是可选的；它们在数据库中的字段是可空的。

权限

在 app/models/Permission.php 中创建一个权限模型，请参考以下示例

<?php namespace App;

use Michalisantoniou6\Cerberus\CerberusPermission;

class Permission extends CerberusPermission
{
}

Permission 模型与 Role 模型具有相同的三个属性

• name — 权限的唯一名称，用于在应用程序层查找权限信息。例如："create-post"、"edit-user"、"post-payment"、"mailing-list-subscribe"。
• display_name — 权限的人类可读名称。不一定唯一且为可选项。例如："创建帖子"、"编辑用户"、"发布支付"、"订阅邮件列表"。
• description — 对权限的更详细说明。

一般来说，可以将最后两个属性以句子的形式考虑："权限 display_name 允许用户 description。"。

用户

对于单租户站点，请在现有的 User 模型中使用 CerberusUserTrait 特性。例如

<?php

use Michalisantoniou6\Cerberus\Traits\CerberusUserTrait;

class User extends Eloquent
{
    use CerberusUserTrait; // add this trait for a single tenancy site
    
    //...
}

这将启用与 Role 的关系，并在您的 User 模型中添加以下方法：roles()、hasRole($name)、hasPermission($permission) 和 ability($roles, $permissions, $options)。

composer dump-autoload

如果您想使用多租户功能，请使用 CerberusSiteUserTrait。例如

<?php

use Michalisantoniou6\Cerberus\Traits\CerberusSiteUserTrait;

class User extends Eloquent
{
    use CerberusSiteUserTrait; //add this trait for a multi-tenant site
    
    //...
}

这将启用与 Role 的关系，并在您的 User 模型中添加以下方法：roles()、hasRoleForSite($name, $site)、hasPermissionForSite($permission, $site) 和 abilityForSite($roles, $permissions, $site, $options)。您还将有 hasRole($name) 和 hasPermission($permission) 可用，以防您想针对某个特定角色的所有用户。

别忘了运行 composerautoload

现在您就可以开始了。

软删除

默认迁移利用了枢轴表中的 onDelete('cascade') 子句来删除父记录时删除关系。如果出于某种原因您无法在数据库中使用级联删除，则 CerberusRole 和 CerberusPermission 类以及 HasRole 特性包含事件监听器以手动删除相关枢轴表中的记录。出于防止意外删除数据的目的，事件监听器将 不会 删除枢轴数据，如果模型使用软删除。然而，由于 Laravel 事件监听器的限制，无法区分对 delete() 的调用与对 forceDelete() 的调用。因此，在强制删除模型之前，您必须手动删除任何关系数据（除非您的枢轴表使用级联删除）。例如

$role = Role::findOrFail(1); // Pull back a given role

// Regular Delete
$role->delete(); // This will work no matter what

// Force Delete
$role->users()->sync([]); // Delete relationship data
$role->perms()->sync([]); // Delete relationship data

$role->forceDelete(); // Now force delete will work regardless of whether the pivot table has cascading delete

用法

概念

让我们首先创建以下 Role 和 Permission

$owner = new Role();
$owner->name         = 'owner';
$owner->display_name = 'Project Owner'; // optional
$owner->description  = 'User is the owner of a given project'; // optional
$owner->save();

$admin = new Role();
$admin->name         = 'admin';
$admin->display_name = 'User Administrator'; // optional
$admin->description  = 'User is allowed to manage and edit other users'; // optional
$admin->save();

创建这两个角色后，让我们将它们分配给用户。多亏了 HasRole 特性，这非常简单

$user = User::where('username', '=', 'michele')->first();

// role attach alias
$user->attachRole($admin); // parameter can be an Role object, array, or id

// or eloquent's original technique
$user->roles()->attach($admin->id); // id only

现在我们只需要将权限添加到这些角色中

$createPost = new Permission();
$createPost->name         = 'create-post';
$createPost->display_name = 'Create Posts'; // optional
// Allow a user to...
$createPost->description  = 'create new blog posts'; // optional
$createPost->save();

$editUser = new Permission();
$editUser->name         = 'edit-user';
$editUser->display_name = 'Edit Users'; // optional
// Allow a user to...
$editUser->description  = 'edit existing users'; // optional
$editUser->save();

$admin->attachPermission($createPost);
// equivalent to $admin->perms()->sync(array($createPost->id));

$owner->attachPermissions(array($createPost, $editUser));
// equivalent to $owner->perms()->sync(array($createPost->id, $editUser->id));

检查角色 & 权限

现在我们可以简单地通过以下操作来检查角色和权限

$user->hasRole('owner');   // false
$user->hasRole('admin');   // true
$user->hasPermission('edit-user');   // false
$user->hasPermission('create-post'); // true

hasRole() 和 can() 都可以接收一个包含要检查的角色和权限的数组

$user->hasRole(['owner', 'admin']);       // true
$user->hasPermission(['edit-user', 'create-post']); // true

默认情况下，如果用户拥有任何角色或权限，则该方法将返回 true。将 true 作为第二个参数传递会指示该方法要求 所有 项目。

$user->hasRole(['owner', 'admin']);             // true
$user->hasRole(['owner', 'admin'], true);       // false, user does not have admin role
$user->hasPermission(['edit-user', 'create-post']);       // true
$user->hasPermission(['edit-user', 'create-post'], true); // false, user does not have edit-user permission

对于每个 User，您可以根据需要拥有任意多的 Role，反之亦然。

Cerberus 类为当前登录用户提供了对 can() 和 hasRole() 的快捷方式。

Cerberus::hasRole('role-name');
Cerberus::hasPermission('permission-name');

// is identical to

Auth::user()->hasRole('role-name');
Auth::user()->hasPermission('permission-name');

您还可以使用占位符（通配符）来检查任何匹配的权限，方法如下：

// match any admin permission
$user->hasPermission("admin.*"); // true

// match any permission about users
$user->hasPermission("*_users"); // true

用户能力

可以使用强大的 ability 函数进行更高级的检查。它接受三个参数（角色、权限、选项）。

• roles 是要检查的角色集合。
• permissions 是要检查的权限集合。

角色或权限变量可以是逗号分隔的字符串或数组。

$user->ability(array('admin', 'owner'), array('create-post', 'edit-user'));

// or

$user->ability('admin,owner', 'create-post,edit-user');

这将检查用户是否具有提供的任何角色和权限。在这种情况下，它将返回 true，因为用户是 admin 并且拥有 create-post 权限。

第三个参数是选项数组。

$options = array(
    'validate_all' => true | false (Default: false),
    'return_type'  => boolean | array | both (Default: boolean)
);

• validate_all 是一个布尔标志，用于设置是否检查所有值都为 true，或者只要至少匹配一个角色或权限就返回 true。
• return_type 指定返回布尔值、已检查值的数组，或者同时返回两者。

以下是一个示例输出：

$options = array(
    'validate_all' => true,
    'return_type' => 'both'
);

list($validate, $allValidations) = $user->ability(
    array('admin', 'owner'),
    array('create-post', 'edit-user'),
    $options
);

var_dump($validate);
// bool(false)

var_dump($allValidations);
// array(4) {
//     ['role'] => bool(true)
//     ['role_2'] => bool(false)
//     ['create-post'] => bool(true)
//     ['edit-user'] => bool(false)
// }

Cerberus 类为当前登录用户提供了对 ability() 的快捷方式。

Cerberus::ability('admin,owner', 'create-post,edit-user');

// is identical to

Auth::user()->ability('admin,owner', 'create-post,edit-user');

Blade 模板

在您的 Blade 模板中可用三个指令。您提供的指令参数将直接传递给相应的 Cerberus 函数。

@role('admin')
    <p>This is visible to users with the admin role. Gets translated to 
    \Cerberus::role('admin')</p>
@endrole

@permission('manage-admins')
    <p>This is visible to users with the given permissions. Gets translated to 
    \Cerberus::hasPermission('manage-admins'). The @can directive is already taken by core 
    laravel authorization package, hence the @permission directive instead.</p>
@endpermission

@ability('admin,owner', 'create-post,edit-user')
    <p>This is visible to users with the given abilities. Gets translated to 
    \Cerberus::ability('admin,owner', 'create-post,edit-user')</p>
@endability

同样，您可以将 Blade 指令用于多租户方法。

@roleforsite('admin', 15)
    <p>This is visible to users with the admin role for site with id 15. Gets translated to 
    \Cerberus::roleForSite('admin', 15)</p>
@endroleforsite

@permissionforsite('manage-admins', 15)
    <p>This is visible to users with the given permissions for site with id 15. Gets translated to 
    \Cerberus::hasPermissionForSite('manage-admins', 15). The @can directive is already taken by core 
    laravel authorization package, hence the @permission directive instead.</p>
@endpermissionforsite

@abilityforsite('admin,owner', 'create-post,edit-user', 15)
    <p>This is visible to users with the given abilities for site with id 15. Gets translated to 
    \Cerberus::abilityForSite('admin,owner', 'create-post,edit-user', 15)</p>
@endabilityforsite

中间件

您可以使用中间件根据权限或角色过滤路由和路由组。

Route::group(['prefix' => 'admin', 'middleware' => ['role:admin']], function() {
    Route::get('/', 'AdminController@welcome');
    Route::get('/manage', ['middleware' => ['permission:manage-admins'], 'uses' => 'AdminController@manageAdmins']);
});

可以使用管道符号作为 OR 运算符。

'middleware' => ['role:admin|root']

要模拟 AND 功能，只需使用多个中间件实例。

'middleware' => ['role:owner', 'role:writer']

对于更复杂的情况，使用接受 3 个参数的 ability 中间件：角色、权限、validate_all。

'middleware' => ['ability:admin|owner,create-post|edit-user,true']

故障排除

如果在迁移过程中遇到类似以下错误：

SQLSTATE[HY000]: General error: 1005 Can't create table 'laravelbootstrapstarter.#sql-42c_f8' (errno: 150)
    (SQL: alter table `role_user` add constraint role_user_user_id_foreign foreign key (`user_id`)
    references `users` (`id`)) (Bindings: array ())

那么可能是因为您的用户表中的 id 列与 role_user 中的 user_id 列不匹配。请确保两者都是 INT(10)。

在尝试使用 CerberusUserTrait 方法时，如果遇到类似以下错误：

Class name must be a valid object or a string

那么可能是因为您尚未发布 Cerberus 资产，或者发布过程中出现了错误。首先，请检查您的 config 目录中是否有 cerberus.php 文件。如果没有，请尝试运行 php artisan vendor:publish，如果它仍然没有出现，请手动将 /vendor/zizaco/cerberus/src/config/config.php 文件复制到您的配置目录中，并重命名为 cerberus.php。

许可证

Cerberus 是在 MIT 许可证条款下分发的免费软件。

贡献指南

遵循 PSR-1 和 PSR-4 PHP 编码标准和语义版本控制。

请在问题页面报告您找到的任何问题。
欢迎提交拉取请求。

致谢

本软件包最初是从 Zicaco/Entrust 分支出来的。它提供了与原始软件包相同的特性，同时还具备多租户站点的功能。