README

Entrust是一种简洁灵活的方式，用于将基于角色的权限添加到Laravel 4。

首先，我必须感谢此包的原始开发者。Andrew Elkins (@andrewelkins) 和 Leroy Merlin (@zizaco) 在基本设计和功能方面做了出色的工作。我的分支旨在

删除与角色和权限管理不相关的额外组件（特别是，Ardent）。
添加我认为有用的额外功能，尤其适合此包。
使包的集成更加灵活和动态（最终）。

如果我的更改被集成回Zizaco版本的此插件，那将非常令人愉快。无论如何，我希望能够展示一些真正有用的功能和选项。

内容

快速入门
- 所需设置
配置
- 用户与角色之间的关系
- 模型
用法
故障排除
许可证
附加信息

快速入门

PS：即使不需要，Entrust也能很好地与Confide配合使用，以消除涉及用户管理的重复任务：账户创建、登录、登出、电子邮件确认、密码重置等。

看看Confide.

所需设置

在composer.json文件的require键中添加以下内容

"bbatsche/entrust": "~2.0"

运行Composer更新命令

composer update

在您的config/app.php中将'Bbatsche\Entrust\EntrustServiceProvider'添加到$providers数组的末尾

'providers' => array(
    'Illuminate\Foundation\Providers\ArtisanServiceProvider',
    'Illuminate\Auth\AuthServiceProvider',
    // ...
    'Bbatsche\Entrust\EntrustServiceProvider',
),

在config/app.php的末尾添加'Entrust' => 'Bbatsche\Entrust\EntrustFacade'到$aliases数组

'aliases' => array(
    'App'        => 'Illuminate\Support\Facades\App',
    'Artisan'    => 'Illuminate\Support\Facades\Artisan',
    // ...
    'Entrust'    => 'Bbatsche\Entrust\EntrustFacade',
),

配置

在config/auth.php中设置属性值（通常，这些值默认配置正确，但值得再次检查）。这些值将被Entrust用于引用正确的用户表和模型。

您还可以发布此包的配置以进一步自定义表名和模型命名空间

php artisan config:publish bbatsche/entrust

用户与角色之间的关系

现在生成Entrust迁移

php artisan entrust:migration

它将生成<timestamp>_entrust_setup_tables.php迁移。您现在可以使用artisan migrate命令运行它

php artisan migrate

迁移后，将出现四个新表

roles - 存储角色记录
permissions - 存储权限记录
role_user - 存储角色和用户之间的多对多关系
permission_role - 存储角色和权限之间的多对多关系

模型

角色

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

<?php

use Bbatsche\Entrust\Contracts\EntrustRoleInterface;
use Bbatsche\Entrust\Traits\EntrustRoleTrait;

class Role extends Eloquent implements EntrustRoleInterface
{
    use EntrustRoleTrait;
}

Role模型有三个主要属性

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

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

权限

在 app/models/Permission.php 内创建一个 Permission 模型，以下是一个示例

<?php

use Bbatsche\Entrust\Contracts\EntrustPermissionInterface;
use Bbatsche\Entrust\Traits\EntrustPermissionTrait;

class Permission extends Eloquent implements EntrustPermissionInterface
{
    use EntrustPermissionTrait;
}

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

name — 权限的唯一名称，用于在应用层查找权限信息。例如：“创建帖子”、“编辑用户”、“发布付款”、“订阅邮件列表”。
display_name — 权限的可读名称。不一定唯一，可选。例如：“创建帖子”、“编辑用户”、“发布付款”、“订阅邮件列表”。
description — 对权限的更详细说明。

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

用户

最后，将相同的 traits 和 role 模式添加到您的用户模型中。例如

<?php

use Bbatsche\Entrust\Contracts\EntrustUserInterface;
use Bbatsche\Entrust\Traits\EntrustUserTrait;

class User extends Eloquent implements EntrustUserInterface
{
    use EntrustUserTrait;

    ...
}

这将启用与 Role 的关系，并在您的 User 模型中添加几个用于检查角色或权限的方法。

别忘了运行 composer autoload

composer dump-autoload

现在您就可以开始了。

非标准表名

默认情况下，Entrust 配置为遵循 Laravel 的命名约定，因此您的 Role 模型的数据存储在一个名为 roles 的表中。如果您更改了 Entrust 的默认配置，您也需要在模型中反映这些更改。这可以通过添加以下构造函数来完成

角色构造函数

public function __construct($attr = array())
{
    $this->table = Config::get('entrust::roles_table');

    parent::__construct($attr);
}

权限构造函数

public function __construct($attr = array())
{
    $this->table = Config::get('entrust::permissions_table');

    parent::__construct($attr);
}

EntrustRole和EntrustPermission类

为了方便使用（和向后兼容），Entrust 包含了抽象类 Bbatsche\Entrust\EntrustRole 和 Bbatsche\Entrust\EntrustPermission。您的 Role 和 Permission 模型可以简单地扩展这些类，这些类实现了它们各自的接口和 traits。它们还包括上述构造函数。根据您的需求，这些可能在您的模型中更容易实现。

软删除

默认迁移利用了连接表中的 onDelete('cascade') 子句，在删除父记录时删除关系。如果出于某种原因您无法在数据库中使用级联删除，EntrustRoleTrait、EntrustPermissionTrait 和 EntrustUserTrait 包含事件监听器，可手动删除相关连接表中的记录。为了防止意外删除数据，事件监听器将在模型使用软删除时不会删除连接数据。然而，由于 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();

在创建了这两个角色后，让我们将它们分配给用户。多亏了 EntrustUserTrait，这就像

$user = User::where('username', '=', 'bbatsche')->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()->attach($createPost->id);

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

检查角色和权限

现在我们可以通过简单地使用 is() 方法来检查角色

$user->is('owner'); // false
$user->is('admin'); // true

如果您想检查多个角色，您可以使用 isAny() 或 isAll()，具体取决于您只需要一个角色还是所有角色

$user->isAny(['owner', 'admin']); // true
$user->isAll(['owner', 'admin']); // false, $user does not have the 'owner' role

如果您需要更多关于哪些角色失败的信息，可以将变量传递到第二个参数。在调用 isAny() 或 isAll() 之后，该变量将是一个包含失败角色的数组。

$failedRoles = array();

$user->isAny(['owner', 'admin'], $failedRoles); // true
// or
$user->isAll(['owner', 'admin'], $failedRoles); // false

print_r($failedRoles);
// Array
// (
//      [0] => owner
// )

类似地，如果我们想检查用户的权限，我们使用方法 can()

$user->can('create-post'); // true
$user->can('edit-user');   // false

与角色类似，检查多个权限也有相应的办法；canAny() 和 canAll()

$user->canAny(['create-post', 'edit-user']); // true
$user->canAll(['create-post', 'edit-user']); // false, $user doesn't have 'edit-user' permission

这些方法还可以包括一个变量来跟踪哪个具体的权限失败

$failedPerms = array();

$user->canAny(['create-post', 'edit-user'], $failedPerms); // true
// or
$user->canAll(['create-post', 'edit-user'], $failedPerms); // false

print_r($failedPerms);
// Array
// (
//      [0] => edit-user
// )

您可以为每个 User 设置任意数量的 Role，并且每个 Role 可以拥有所需的所有 Permissions。

Entrust 类为当前登录用户提供了对 is*() 和 can*() 方法的快捷方式

Entrust::is('role-name');
Entrust::can('permission-name');

// are identical to

Auth::user()->is('role-name');
Auth::user()->can('permission-name);

Entrust::isAny(['role-name-1', 'role-name-2', /* ... */]);
Entrust::isAll(['role-name-1', 'role-name-2', /* ... */]);

Entrust::canAny(['permission-name-1', 'permission-name-2', /* ... */]);
Entrust::canAll(['permission-name-1', 'permission-name-2', /* ... */]);

// are identical to

Auth::user()->isAny(['role-name-1', 'role-name-2', /* ... */]);
Auth::user()->isAll(['role-name-1', 'role-name-2', /* ... */]);

Auth::user()->canAny(['permission-name-1', 'permission-name-2', /* ... */]);
Auth::user()->canAll(['permission-name-1', 'permission-name-2', /* ... */]);

注意： Laravel Facades 不支持按引用传递，这意味着您不能将第二个参数传递给 *Any() 和 *All() 方法以找出确切的哪些权限或角色失败。为此，您必须获取 User 对象的实例。

用户能力

可以使用 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)
// }

控制器特性

通常在创建控制器时，您会发现有一些角色或权限您希望在每个操作的基础上强制执行。Entrust 为您的控制器提供了一个特性，使得执行这些规则变得非常简单。首先，您必须在控制器中使用这个特性。例如，我们可以在 BaseController 中包含它，以便在所有控制器中都可以使用这个特性

<?php

use Bbatsche\Entrust\Traits\EntrustControllerTrait;

class BaseController extends Controller
{
    use EntrustControllerTrait;
}

该特性包含两个可用于过滤请求到控制器的方法，它们是 entrustPermissionFilter() 和 entrustRoleFilter()。要在控制器中启用一个或两个这些过滤器，请使用控制器构造函数中的 beforeFilter() 方法

public function __construct()
{
    $this->beforeFilter('@entrustRoleFilter');

    // and / or

    $this->beforeFilter('@entrustPermissionFilter');
}

所需的角色或权限在控制器的属性中指定；可以是 $entrustPerms 或 $entrustRoles。这些属性应该是关联数组，键是控制器操作（或方法）的名称，值是该操作所需的角色或权限。角色和权限可以是字符串或多个值的数组。例如

protected $entrustPerms = array(
    'create'  => 'post-create',
    'edit'    => ['post-edit-own',    'post-edit'],
    'destroy' => ['post-destroy-own', 'post-destroy']
);

protected $entrustRoles = array(
    'index'  => ['owner', 'admin'],
    'store'  => 'owner',
    'update' => 'owner'
);

Entrust 将自动检查这些角色或权限与控制器中的每个方法。如果当前用户没有所需的角色或权限，将返回一个 403 响应。

控制器特质包含一些可选标志，用于控制它如何解释权限和角色的数组。当指定的值是数组时，Entrust假定任何实体都足够。要强制Entrust要求所有值，请将控制器中的属性$entrustRequireAll设置为true。此外，如果您的数组中没有指定方法，过滤器将其视为“通过”。为了使Entrust要求为所有操作指定角色或权限，请将属性$entrustAllowMissing设置为false。此设置可能有助于进行安全检查，意味着如果未指定操作的角色或权限，则用户不应能够访问它。

如果您希望在过滤器失败后进行一些额外的处理，可以创建回调函数。回调函数可以通过以下三种方式之一指定。首先，您可以创建名为entrustPermissionCallback()或entrustRoleCallback()的方法。其次，您可以创建一个闭包并将其分配给控制器中的$entrustPermisionCallback或$entrustRoleCallback属性。或者最后，您可以单独创建该方法并将其名称作为字符串分配给这些属性之一。在任何情况下，每当其中一个过滤器失败时，Entrust都会调用您的回调函数。它将以下内容传递给您的函数

控制器方法名称
失败权限或角色
所需的全部权限或角色集合
Route对象
Request对象

一个示例回调函数可能如下所示

public function entrustPermissionCallback($method, $failedPerms, $allPerms)
{
    if (empty($allPerms)) {
        // No perms defined but filter still failed, meaning user was not authenticated
        App::abort(401, 'You do not have permission to view this page, please log in.');
    }

    // Empty failed perms means user was not authenticated
    // Act as if *all* perms failed instead
    $failedPerms = $failedPerms ?: $allPerms;

    $join = $this->entrustRequireAll ? 'and' : 'or';

    $desc = Permission::whereIn('name', (array)$failedPerms)->lists('description');

    switch (count($desc)) {
        case 1:
            $message = "You do not have permission to {$desc[0]}!";
            break;
        case 2:
            $message = "You do not have permission to {$desc[0]} $join {$desc[1]}!";
            break;
        default:
            $last = array_pop($desc);

            $message = 'You do not have permission to ' . implode(', ', $desc) . ", $join $last!";
            break;
    }

    App::abort(403, $message);
}

简短语法路由过滤器

要按权限或角色过滤路由，您可以在app/filters.php中调用以下内容

// only users with roles that have the 'manage_posts' permission will be able to access any route within admin/post
Entrust::routeNeedsPermission('admin/post*', 'create-post');

// only owners will have access to routes within admin/advanced
Entrust::routeNeedsRole('admin/advanced*', 'owner');

// optionally the second parameter can be an array of permissions or roles
// user would need to match all roles or permissions for that route
Entrust::routeNeedsPermission('admin/post*', array('create-post', 'edit-comment'));
Entrust::routeNeedsRole('admin/advanced*', array('owner','writer'));

这两种方法都接受第三个参数。如果第三个参数为null，则禁止访问的返回值将是App::abort(403)，否则将返回第三个参数。因此，您可以使用它

Entrust::routeNeedsRole('admin/advanced*', 'owner', Redirect::to('/home'));

此外，这两种方法都接受第四个参数。默认为true，检查所有提供的角色/权限。如果将其设置为false，则函数只有在所有角色/权限都失败时才会失败。这对于需要允许多个组访问的行政应用程序很有用。

// if a user has 'create-post', 'edit-comment', or both they will have access
Entrust::routeNeedsPermission('admin/post*', array('create-post', 'edit-comment'), null, false);

// if a user is a member of 'owner', 'writer', or both they will have access
Entrust::routeNeedsRole('admin/advanced*', array('owner','writer'), null, false);

// if a user is a member of 'owner', 'writer', or both, or user has 'create-post', 'edit-comment' they will have access
// if the 4th parameter is true then the user must be a member of Role and must have Permission
Entrust::routeNeedsRoleOrPermission(
    'admin/advanced*',
    array('owner', 'writer'),
    array('create-post', 'edit-comment'),
    null,
    false
);

路由过滤器

可以通过在门面中使用can和hasRole方法在过滤器中直接使用Entrust角色/权限。

Route::filter('manage_posts', function()
{
    // check the current user
    if (!Entrust::can('create-post')) {
        return Redirect::to('admin');
    }
});

// only users with roles that have the 'manage_posts' permission will be able to access any admin/post route
Route::when('admin/post*', 'manage_posts');

使用过滤器检查角色

Route::filter('owner_role', function()
{
    // check the current user
    if (!Entrust::hasRole('Owner')) {
        App::abort(403);
    }
});

// only owners will have access to routes within admin/advanced
Route::when('admin/advanced*', 'owner_role');

如你所见，Entrust::hasRole()和Entrust::can()检查用户是否已登录，然后检查他们是否有该角色或权限。如果用户未登录，则返回值也将是false。

故障排除

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

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)。

许可证

Entrust是免费软件，根据MIT许可证条款发布。

bbatsche / entrust

维护者

详细信息