README

功能管理器 是一个库，它允许更好地控制和检查功能以及每个功能的允许操作。

如何？

系统通常有一些 作用域、角色 或甚至 权限 和 功能，这些权限通常附加到操作上。此库假设存在以下操作

当然，您可以使用 \Piggly\CapabilitiesManager\Enum\CapabilityOperations 类自定义它们。使用 add() 方法添加新操作，使用 remove() 方法删除操作，并使用 set() 方法将完全新的 数组 操作设置为操作。

然后，这些操作可以附加到功能上。例如，下面是一些功能示例

如果您想或您的系统需要，可以仅忽略操作行为并仅使用功能键。此库可以支持它。

如果用户可能只能读取帖子，他的功能将是 posts:read。我们可以以一种智能且简单的方式实现这一点

use Piggly\CapabilitiesManager\Capability;
use Piggly\CapabilitiesManager\Capabilities;

$caps = new Capabilities();
$caps->add((new Capability())->setKey('posts')->add('read'));

如果相同的用户还可以读取/编辑评论怎么办？

use Piggly\CapabilitiesManager\Capability;
use Piggly\CapabilitiesManager\Capabilities;

$caps = new Capabilities();
$caps
	->add((new Capability())->setKey('posts')->add('read'))
	->add((new Capability())->setKey('comments')->add('read', 'write'));

请记住，功能 对象不关心操作的顺序，这意味着 add('read', 'write') 与 add('write', 'read') 相同。

某种程度上，同一个用户可以在 page 功能上执行任何操作。所以

use Piggly\CapabilitiesManager\Capability;
use Piggly\CapabilitiesManager\Capabilities;

$caps = new Capabilities();
$caps
	->add((new Capability())->setKey('posts')->add('read'))
	->add((new Capability())->setKey('comments')->add('read', 'write'))
	->add((new Capability())->setKey('pages')->allowAny();

功能语法

但，还有一种简单且紧凑的方式来添加/创建功能。通过使用功能语法，语法如下： <capability_key>:<operation>,...,<operation>。见下文

use Piggly\CapabilitiesManager\Capability;
use Piggly\CapabilitiesManager\Capabilities;

$caps = new Capabilities();
$caps
	->add(new Capability('posts:read'))
	->add(new Capability('comments:read,write'))
	->add(new Capability('pages'));

或者通过空格字符分隔功能语法，更加紧凑

use Piggly\CapabilitiesManager\Capability;
use Piggly\CapabilitiesManager\Capabilities;

$caps = new Capabilities('posts:read comments:read,write pages');

如果您没有在语法中附加操作，例如上面的 page，功能语法将允许对那个功能的任何操作。如果您想改变这种行为，您将需要发送一些默认操作。

use Piggly\CapabilitiesManager\Capability;
use Piggly\CapabilitiesManager\Capabilities;

$caps = new Capabilities('posts:read comments:read,write pages', ['read']);

现在 pages 只允许 read 操作。

如果功能对象中的功能语法有错误，Capability 对象将抛出 InvalidArgumentException。例如，如果您创建 comments:read,write,unknown，将抛出异常，因为 unknown 不是一个有效的操作。

它如何帮助我？

创建功能后，您可以对它们做很多事情，例如

使用 isMatching() 方法检查一个 Capabilities 对象是否与另一个对象具有完全相同的功能和操作；
使用 isFitting() 方法检查一个 Capabilities 对象是否适合另一个对象；
使用 isAllowed() 方法检查在 Capabilities 对象中是否允许功能和使用操作；
使用 isAnyAllowed() 方法检查在 Capabilities 对象中是否允许任何所需操作；
使用 isAllAllowed() 方法检查在 Capabilities 对象中是否允许所有所需操作；
您可以使用 add()、merge()、remove()、removeMany() 和 get() 方法在 Capabilities 对象中管理功能；
您可以将 Capabilities 对象 serialize，转换为 json，转换为 array 或甚至转换为 string。

现实世界中的最小示例

use Piggly\CapabilitiesManager\Capability;
use Piggly\CapabilitiesManager\Capabilities;

// Getting sent capabitities
$caps = filter_input ( INPUT_POST, 'capabilities', FILTER_SANITIZE_STRING );

// Create capabilities
try
{ $caps = new Capabilities($caps); }
catch ( Exception $e )
{ return 'You capability syntax is invalid.'; }

// You can save this capabilities to user of many ways:

$user->setCapabilities($caps->toJson())->save(); // json format
$user->setCapabilities((string)$caps)->save(); // string format
$user->setCapabilities(serialize($caps))->save(); // serialized format

// ... soon, you can read accordingly
$caps = (new Capabilities())->fromJson($user->getCapabilities()); // json format
$caps = new Capabilities($user->getCapabilities()); // string format
$caps = unserialize($user->getCapabilities()); // unserialized format

// To better control user data, you have to do the User object manages Capabilities object:
// Class below is a simple sample
class User
{
	// ...
	public function setCapabilities ( Capabilities $caps )
	{ $this->caps = $caps; }

	public function getCapabilities () : Capabilities
	{ return $caps; }

	public function save ()
	{
		// ...
		$this->caps = (string) $caps;
		DB::save($this);
	}
	
	public function load ()
	{
		$data = DB::load($this);
		// ...
		$this->caps = new Capabilities($data['caps']);
	}
}

// ... then, user may try to access a middleware requiring some capability and operation
$required_capability = 'posts';
$required_operation = 'read';

if ( !$caps->isAllowed($required_capability, $required_operation) )
{ /** User cannot access it **/ }

Capabilities 类灵活，可以通过在任何类型的系统中管理用户/客户端的功能来实现许多目标。

更新日志

查看变更日志文件以获取所有代码更改的信息。

代码测试

此库使用PHPUnit。我们对该应用程序的所有主要类进行了测试。

vendor/bin/phpunit

贡献

在提交您的贡献之前，请参阅贡献文件以获取信息。

鸣谢

支持项目

Piggly Studio是一家位于巴西里约热内卢的代理商。如果您喜欢这个库并希望支持这项工作，请随意向以下BTC钱包捐赠任何金额：3DNssbspq7dURaVQH6yBoYwW3PhsNs8dnK ❤。

许可证

MIT许可证（MIT）。请参阅许可证。

piggly / php-capabilities-manager

维护者

详细信息