README

概述

此包允许您在应用程序中使用具有权限的简单角色。角色在'permissions.php'配置文件中配置，包含角色列表、它们的权限（允许的操作）以及可选的继承的一组角色。

以下是一个简单的permissions配置文件示例

return [
    'roles' => [
        'super-admin' 	=> [			//role name
            'permissions' => '*'        //permissions or wildcard
        ],
		
        'store-admin'	=> [			//role name
            'permissions' => [			//permission list (keyword: permissions)
                'store' => [			//scope
                    'manage'			//permission
                ],
                'items' => '*'
            ],
            
            'roles' => [				//inherited role list (keyword: roles / inherits)
                'customer',				//role
                'store-clerk',			//role
            ],
        ],
        
        'store-clerk' => [
            'permissions' => [
                'greet-customers',
                //... other permissions
            ],
        ],
        
        //other roles
    ],
];

您可以将'store-admin'角色添加到用户中

$user->setRole('store-admin');

您可以通过以下方式检查用户的不同权限

$user->hasPermission('store:manage');           //true
$user->hasPermission('store:delete');           //false

$user->hasPermission('items.any-permission');   //true
$user->hasPermission('greet-customers');        //true (inherited from role: store-clerk)

安装

通过composer在您的Laravel项目中安装此包

composer require antonioprimera/laravel-basic-permissions

该包提供了一个迁移，它将角色列添加到users表中，因此您应该运行artisan migrate命令

php artisan migrate

将AntonioPrimera\BasicPermissions\ActorInterface接口和AntonioPrimera\BasicPermissions\ActorRolesAndPermissions特质添加到您的User模型中。

接下来，您应该像这样向您的User模型添加自定义属性转换

protected $casts = [
    'role' => \AntonioPrimera\BasicPermissions\RoleCast::class,
    //...other attribute casts
];

这将把角色属性转换为Role实例。

用法

基本用法在上面的概述部分中的示例中进行了演示。

设置角色

只需将您配置的角色之一或预配置的super-admin角色添加到用户模型（或任何其他实现此包中ActorInterface的actor）中。

$user->setRole('store-admin');

如果您为role属性使用自定义RoleCast类，您可以通过将Role实例分配给模型的role属性来设置角色

$user->role = new \AntonioPrimera\BasicPermissions\Role('store-admin');
$user->save();

查询角色权限

在您的Laravel策略中，您可以根据角色是否允许特定操作来检查分配给actor的角色，这意味着它具有特定权限（无论是直接还是从另一个角色继承的）

if ($user->hasPermission('store:manage'))
    //do something

一次性查询多个权限

您可以通过检查actor是否允许从权限列表中的所有权限来检查

//provide the list of permissions as an array
if ($user->hasAllPermissions(['store:manage', 'items:move', 'items:sell']))
    //do something only if the actor has all the above permissions

//OR

//provide the list of permissions as separate arguments
if ($user->hasAllPermissions('store:manage', 'items:move', 'items:sell'))
    //do something only if the actor has all the above permissions

您可以通过检查actor是否允许权限列表中的至少一个权限来检查

//provide the list of permissions as an array
if ($user->hasAnyPermission(['store:manage', 'items:move', 'items:sell']))
    //do something if the actor has at least one of the above permissions

//OR

//provide the list of permissions as separate arguments
if ($user->hasAnyPermission('store:manage', 'items:move', 'items:sell'))
    //do something if the actor has at least one of the above permissions

配置

您可以在permissions.php配置文件中配置您的角色，在roles键下，如上文中概述部分中的示例。

每个角色都应该有一个权限列表，维护在它的permissions或actions属性中，并且可以可选地有一个roles或inherits属性，指定一组继承的角色。

权限

权限可以是简单字符串的数组（如上例中的['greet-customer', ...]），也可以嵌套在数组中（如上例中的'store:manage'）。嵌套权限通过其列（':'）分隔的路径来标识。

星号（'*'）通配符可以用于任何权限级别，可以用任何权限（直接或嵌套）替换。参见上文中概述部分的示例，其中'items'权限下有'items'权限下任何权限的'items'权限。此外，您可以看到'超级管理员'角色应该允许任何操作，因为对该角色的任何权限查询都将返回true。 注意：通配符权限应作为独立的字符串提供，而不是放在数组内

权限集类似于权限白名单。未明确添加或继承的权限将不允许。例如，您不能拒绝角色继承的特定权限。

继承的角色

一旦定义了角色，除了其自身的权限外，还可以继承其他角色的权限，而这些角色也可以继承其他权限（任何继承深度）。尽管如此，即使您定义了具有循环继承的角色（例如，role_1 继承 role_2，而 role_2 又继承 role_1），应用程序也不会崩溃，但这可能产生意外的结果，因此请尽量避免。

您可以使用 roles 数组键来定义继承的角色数组。您选择哪个键是个人喜好问题——它们的范围是相同的。

权限标签

为了向人类展示角色，您可以在每个角色中添加一个 label 属性。此标签可用于下拉菜单或显示 UI 中的角色。如果没有提供标签，将使用角色名称。

角色标签可以作为字符串或作为包含翻译的数组提供。当提供翻译时，应用程序将尝试使用当前区域设置来显示标签。如果找不到当前区域设置的翻译，将使用后备区域设置。

以下是一个具有英语和西班牙语标签的角色示例

'store-admin'	=> [
    'label' => [
        'en' => 'Store Admin',
        'es' => 'Administrador de Tienda',
    ],
    //...other role attributes
],

权限描述

您可以为每个权限添加描述，该描述可用于在 UI 中显示工具提示或帮助文本。描述可以提供为字符串或包含翻译的数组。当提供翻译时，应用程序将尝试使用当前区域设置来显示描述。如果找不到当前区域设置的翻译，将使用后备区域设置。

以下是一个具有英语和西班牙语描述的权限示例

'store:manage'	=> [
    'description' => [
        'en' => 'Allows the user to manage the store',
        'es' => 'Permite al usuario administrar la tienda',
    ],
    //...other permission attributes
],

字符串和 HTML 表示

可以将角色转换为字符串，这将返回角色标签。如果没有提供标签，将返回角色名称。

角色还可以转换为 HTML，这在显示 blade 文件中的角色时很有用。HTML 表示将返回角色标签。如果没有提供标签，将返回角色名称。

(string) $role; //returns the role label, or the role name if no label is provided

//in a blade file:
{{ $role }} //returns the role label, or the role name if no label is provided

测试特定权限

由于测试是（或应该是）开发过程中的重要部分，因此该包提供了一些内置助手，以实现轻松测试。简单来说，您可以将特定的临时权限添加到行为实例中。正如标签所暗示的，这些权限是临时的，不会保存到数据库或任何配置中。在下一次从数据库获取行为（或创建此行为的全新实例）时，它们将消失。

分配临时/临时权限

在您的测试中，您可能想要检查只有具有特定权限的行为者才能执行特定操作。要向行为者添加单个权限，您可以使用以下语法

$user->assignTemporaryPermission('some:permission:name');

对于此权限的所有检查，只要此用户被销毁并从数据库重新读取，就会返回 true。请注意，临时权限保存在实例上，因此调用 $user->refresh() 不会重置这些临时权限。

移除临时/临时权限

您可以使用以下方法从行为者中移除临时（临时）权限

$user->removeTemporaryPermission('some:permission:name');

清除所有临时/临时权限

您可以使用以下方法从行为者中移除所有临时（临时）权限

$user->clearTemporaryPermissions();

antonioprimera / laravel-basic-permissions

维护者

详细信息