README

处理您的Laravel应用程序的基于角色的权限。

版本兼容性

内容

安装与配置
使用方法
- 概念
  - 检查角色和权限
  - 用户能力
- 中间件
故障排除
许可证
贡献指南
附加信息

安装

您可以通过composer安装Laravel-entrust包

composer require shanmuga/laravel-entrust

注意：如果您使用的是Laravel 5.5以上版本，可以跳过步骤2和3。

打开您的config/app.php并将以下内容添加到providers数组中

Shanmuga\LaravelEntrust\LaravelEntrustServiceProvider::class,

在相同的config/app.php中，将以下内容添加到aliases数组中

'LaravelEntrust'   => Shanmuga\LaravelEntrust\Facades\LaravelEntrustFacade::class,

运行以下命令以发布包配置文件config/entrust.php和config/entrust_seeder.php

php artisan vendor:publish --tag="LaravelEntrust"

打开您的config/entrust.php并将以下内容添加到其中

要生成的迁移文件名

'migrationSuffix' => 'laravel_entrust_setup_tables',

用于授权的模型和表

'user_model' => 'App\Models\User',
'user_table' => 'users',

用于角色和权限的模型名

'models' => [
    'role'          => 'App\Models\Role',
    'permission'    => 'App\Models\Permission',
],

默认的Guard用于执行用户认证，您也可以在检查时手动传递。

'defaults' => [
     'guard'          => 'web',
 ],

您也可以使用多个guards

'defaults' => [
     'guard'          => ['web', 'api'],
 ],

用于角色和权限的表名

'tables' => [
    'roles'             => 'roles',
    'permissions'       => 'permissions',
    'role_user'         => 'role_user',
    'permission_role'   => 'permission_role',
],

用于角色和权限的外键

'foreign_keys' => [
    'user' => 'user_id',
    'role' => 'role_id',
    'permission' => 'permission_id',
],

用于自定义消息的中间件设置，将register设置为true以自动注册，处理是用于哪个处理器，可以是abort或redirect。您还可以配置在授权失败时显示的消息。

'middleware' => [
    'register' => true,
    'handling' => 'abort',
    'handlers' => [
        'abort' => [
            'code' => 403,
            'message' => 'You don\'t Have a permission to Access this page.'
        ],
        'redirect' => [
            'url' => '/',
            'message' => [
                'key' => 'error',
                'content' => 'You don\'t Have a permission to Access this page'
            ]
        ],
    ],
],

运行以下命令以生成迁移和种子

php artisan laravel-entrust:setup

有关创建权限的更多信息，请参阅Entrust Seeder配置。

最后，将LaravelEntrustUserTrait添加到现有的User模型中。例如

<?php

use Shanmuga\LaravelEntrust\Traits\LaravelEntrustUserTrait;

class User extends Model
{
    use LaravelEntrustUserTrait; // add this trait to your user model

    ...
}

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

不要忘记运行composer dump-autoload

composer dump-autoload

现在，您就可以开始了。

软删除

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

$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->permissions()->sync([]); // Delete relationship data

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

使用方法

概念

让我们首先配置entrust_seeder以创建角色和权限：您的config/laratrust_seeder.php文件看起来像这样

<?php
return [
    'role_structure' => [
        'admin' => [
            'users' => 'c,r,u,d',
            'admin' => 'c,r,u,d',
            'profile' => 'r,d'
        ],
        'subadmin' => [
            'users' => 'c,r,u',
            'profile' => 'r,u'
        ],
    ],
    'user_roles' => [
        'admin' => [
            ['name' => "Admin", "email" => "admin@demo.com", "password" => '123456'],
        ],
    ],
    'permissions_map' => [
        'c' => 'create',
        'r' => 'read',
        'u' => 'update',
        'd' => 'delete',
    ],
];

现在用户被创建，并且相应的角色和权限也被分配给该用户。您也可以轻松地附加和解除角色

$user = User::where('username', 'shan')->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

检查角色和权限

现在我们可以通过简单地这样做来检查角色和权限

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

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

$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，反之亦然。

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

Entrust::hasRole('role-name');
Entrust::can('permission-name');
Entrust::hasPermission('permission-name');

// is identical to
Auth::user()->hasRole('role-name');
Auth::user()->can('permission-name');
Auth::user()->hasPermission('permission-name');
Auth::user()->isAbleTo('permission-name');

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

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

用户能力

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

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

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

$user->ability(['admin', 'owner'], ['create-user', 'edit-user']);
// or
$user->ability('admin,owner', 'create-user,edit-user');

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

第三个参数validateAll是一个布尔标志，用于设置是否检查所有值都为true，或者如果至少匹配一个角色或权限，则返回true。它是可选的，默认为false。

中间件

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

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

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

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

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

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

故障排除

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

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

这发生在使用laravel小于5.8时。它使用Integer进行迁移自动递增，但laravel entrust使用BigInteger。所以请确保两者相同。

尝试使用EntrustUserTrait方法时，您会遇到类似以下错误的错误：

Class name must be a valid object or a string

那么你可能没有发布Entrust资产，或者发布时出了问题。首先，检查您的config目录中是否有entrust.php文件。如果没有，则尝试运行php artisan vendor:publish --tag=LaravelEntrust，如果它没有出现，则手动将/vendor/shanmuga/laravel-entrust/src/config/entrust.php文件复制到您的配置目录中。

如果您的应用程序使用自定义命名空间，则您需要告诉entrust您的permission和role模型在哪里，您可以通过编辑config/entrust.php中的配置文件来完成此操作。

'models' => [
     'role'          => 'App\Models\Role',
     'permission'    => 'App\Models\Permission',
 ]

许可证

Laravel-Entrust是免费软件，根据MIT许可证的条款进行分发。

贡献指南

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

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

shanmuga / laravel-entrust

维护者

详细信息