README

Samshal\Acl 为用户认证添加了基于角色的权限系统。通常，它为权限和权限管理提供了轻量级的访问控制列表。

你可能需要它的原因

访问控制列表允许应用程序控制对其区域的访问，它们提供了创建权限、角色、资源并分配创建的权限到角色的灵活接口。

该组件是 ACL 的实现，它使您能够轻松实现用户授权。

类功能

• 创建资源、角色和权限
• 能够在资源上设置权限并将这些权限授予角色。
• 支持角色继承。
• 完全可序列化，可以与任何数据源互操作。
• 与 PHP v8.1+ 兼容
• 易于使用

资源 是根据 ACL 定义的权限来行动的对象。 角色 是请求访问资源的对象，可以通过 ACL 层允许或拒绝。 权限 只是定义在资源上的规则。

主分支的度量

许可证

本软件遵循 MIT 许可证分发。请阅读 LICENSE 了解有关软件可用性和分发的信息。

安装

Samshal\Acl 可通过 Composer/Packagist 获取，因此只需将此行添加到您的 composer.json 文件中

	{
		"require":{
			"samshal/acl":"^2.0"
		}
	}

或者

	composer require samshal/acl

入门

创建 ACL

创建 ACL 组件就像实例化 Samshal\Acl 一样简单。构造函数 目前 不接受任何参数。实例化示例

<?php
	require "vendor/autoload.php";

	use Samshal\Acl;
	use Samshal\Acl\{
		Role\DefaultRole as Role,
		Resource\DefaultResource as Resource,
		Permission\DefaultPermission as Permission
	};

	$acl = new Acl();

向 ACL 添加对象（角色、权限和资源）。

ACL 提供了一个 add 方法来泛型地添加新对象。换句话说，要向 Acl 添加新角色，只需将 Role Object 传递给 ACL 的 add 方法。您也可以为资源执行相同的操作。

角色对象是 \Samshal\Acl\Role\DefaultRole 对象的实例，或者更普遍地，是实现 \Samshal\Acl\Role\RoleInterface 和 \Samshal\Acl\ObjectInterface 协议的对象。它接受要创建的角色的名称作为参数，以及创建角色的描述作为可选的第二参数。

类似地，资源对象是 \Samshal\Acl\Resource\DefaultResource 对象的实例，它也实现了 \Samshal\Acl\Resource\ResourceInterface 和 \Samshal\Acl\ObjectInterface 接口，同样对于权限，它们必须实现 \Samshal\Acl\Permission\PermissionInterface 和 \Samshal\Acl\ObjectInterface 协议或成为 \Samshal\Acl\Permission\DefaultPermission 类的新实例。

通常，角色、资源和权限被称为对象。它们都必须实现 \Samshal\Acl\ObjectInterface 协议。

	...

	$adminRole = new Role("Admin");
	$accountantRole = new Role("Accountant", "This is optional: anybody who`s not an admin is an accountant");

	$acl->add($adminRole);
	$acl->add($accountantRole);

	$patientFinancialHistoryResource = new Resource("patientFinancialHistory");

	$acl->add($patientFinancialHistoryResource);

	$editPermission = new Permission("edit");
	$viewPermission = new Permission("view");

	$acl->add($editPermission, $viewPermission);

	...

在内部，创建的对象存储在完全可序列化的注册表中。这使得从任何地方轻松传输/获取对象变得简单；持久存储、数据库以及任何其他可以存储/接收数据的地方。关于此的更多信息稍后提供。

Samshal\Acl 提供了一种更直观的创建对象的方法。您不需要每次在注册表中添加对象时都创建新的对象，为什么不调用一个方法，该方法可以确定您正在尝试创建哪种类型的对象，并自动执行它呢？ACL 提供了 addRole、addResource 和 addPermission 方法来达到这个目的，这些方法都接受字符串作为参数。示例

	...

	$acl->addRole('Admin');
	$acl->addRole('Accountant');

	$acl->addResource('patientFinancialHistory');

	$acl->addPermission('edit');
	$acl->addPermission('view');

	...

酷吧？添加方法（addRole、addResource、addPermission 和 add）是变长的，它们可以一次性接受无限数量的参数。所以，我们甚至可以在添加角色时使生活不那么无聊。

	...

	$acl->addRole('Admin', 'Accountant');

	...

或者这样为权限。

	...

	$acl->addPermission('edit', 'view', 'create', 'print', 'delete'); //you can add even more permissions!

	...

设置权限。

这个组件存在的原因是在资源上设置权限并授予/拒绝这些权限给角色。下面的代码片段展示了如何设置这些权限的示例。

	...

	/**
	 * In the example below, admin is the name of a Role that's been added to the ACl using add() or addRole().
	 * Similarly view is a permission and patientFinancialHistory is a resource.
	 *
	 * Use the `can` keyword in between a role and a permission in a chain to set make the resource in question accessible or not to the role.
	 */
	$acl->admin->can->view('patientFinancialHistory');

	$acl->accountant->cannot->delete('patientFinancialHistory'); //denying the role Accountant delete right on the PatienFinancialHistory resource.

	...

检查权限

要检查角色在特定资源上的权限，您可以使用以下类似的代码片段

	...

	$booleanResultIndicatingPermission = $acl->can->admin->view('patientFinancialHistory');
	//We are asking a very simple question: can an Admin role View the patientFinancialHistory resource?

	//even better, we could use it in a conditional

	if ($acl->can->accountant->delete('patientFinancialHistory'))
	{
		//delete the patients financial history!
	}
	else
	{
		//this user does not have any permission to delete this resource, let him know that
	}

	...

保持您的 ACL 持久和安全。

\Samshal\Acl 将对象及其上的权限存储在完全可序列化的注册表中。这意味着您可以将整个 acl 转换为字符串并存储在数据库或会话中，使其无限期存在，直到您准备好销毁它或 不再使用它。

如何使用

	...

	$serializedAcl = serialize($acl);

	//store $serializedAcl in a session
	session_start();
	$_SESSION["acl"] = $serializedAcl.

	//or in a db
	$sqlQuery = "INSERT INTO my_tbl VALUES ('$serializedAcl')";

如何检索它

	/**
	 * File Name: patientHistories.php
	 */

	session_start();
	$acl = unserialize($_SESSION["acl"]);

	//use it!
	if ($acl->can->accountant->delete('patientFinanicalHistory'))
	{
		//delete the patients financial history!
	}
	else
	{
		//this user does not have any permission to delete this resource, let him know that
	}

	...

其他有趣的功能

角色 - 角色继承

\Samshal\acl 允许角色从其他角色继承权限。ACL 组件有一个 inherits 方法，该方法接受一个角色对象作为参数。您也可以传入一个字符串，但必须是已存在的角色对象的 id。

自动在所有资源上授予权限。

您还可以不带任何参数调用权限对象。这将在会话中的角色上为 ACL 中定义的所有资源授予相关权限。

此库的维护者

此库目前正在由 Samuel Adeshina 开发和维护

路线图

路线图草案正在进行中。

如何贡献

支持遵循 PSR-2 PHP 编码标准。

请将您在问题页面中发现的任何问题报告。欢迎 Pull 请求。