README

管理Icybee CMS的用户。

权限和所有权

用户可以执行的操作取决于授予他的权限，或者他是否是记录的所有者。

用于确定用户是否有特定权限或是否是记录所有者有两种方法。为了适应各种不同的情况，使用了插件来帮助。

确定用户的权限

方法 has_permission() 确定用户是否有特定权限。这个权限可以相对于一个目标，比如一个模块。

以下示例演示了如何验证用户是否有更新自己资料的权限，或者他是否有管理用户模块的权限。

<?php

use ICanBoogie\Module;

if ($user->has_permission('update own profile')
|| $user->has_permission(Module::PERMISSION_ADMINISTER, $app->modules['users']))
{
	// …
}

如果用户缺少所需的权限，assert_permission() 方法会抛出 UserLacksPermission 异常。

<?php

use Icybee\Modules\Users\UserLacksPermission;

/* @var \Icybee\Modules\Users\User $user */
/* @var \ICanBoogie\Application $app */
/* @var string|int $permission */

$node = $app->models['nodes']->one;

try 
{
	$user->assert_permission($permission, $node);

	// …
}
catch (UserLacksPermission $e)
{
	var_dump($e->permission, $e->resource, $e->user);
}

确定用户所有权

方法 has_ownership() 确定用户是否拥有资源所有权。请注意，所有权 并不等于 权限！用户可能拥有资源，但没有删除它的权限。

以下示例演示了如何验证用户是否是节点的所有者。

<?php

$node = $app->models['nodes']->one;

if ($user->has_ownership($node))
{
	// …
}

如果用户缺少资源所有权，assert_ownership() 方法会抛出 UserLacksOwnership 异常。

<?php

use Icybee\Modules\Users\UserLacksOwnership;

/* @var \Icybee\Modules\Users\User $user */
/* @var \ICanBoogie\Application $app */

$node = $app->models['nodes']->one;

try 
{
	$user->assert_ownership($node);

	// …
}
catch (UserLacksOwnership $e)
{
	var_dump($e->resource, $e->user);
}

一个开放的系统

为了更好地应对各种不同的情况，使用了一个基于插件概念的开放系统。在这个系统中，第三方可以提供对共享所有权的支持，这是用户模块不支持的功能。使用这个系统，角色模块提供了与角色关联的权限的支持。

使用 users 配置定义了解析器。

权限解析器

权限解析器确定用户是否有执行操作所需的权限。例如，角色模块定义的解析器根据用户的角色及其关联的权限确定用户的权限。

权限解析器在 users 配置中的 permission_resolver_list 数组中定义。它可以是函数或实现 PermissionResolverInterface 接口的类的名称。

<?php

// …/config/users.php

return [

	'permission_resolver_list' => [

		'a_resolver' => 'Hooks::my_permission_resolver',
		'another_resolver' => 'MyPermissionResolverClass'

	]

];

所有权解析器

所有权解析器确定用户是否是记录的所有者。由模块定义的解析器认为，如果用户的所有权 uid 属性不为空且与用户的标识符匹配，或者用户是管理员，那么用户是记录的所有者。

<?php

namespace Icybee\Modules\Users;

use ICanBoogie\ActiveRecord;

function(User $user, ActiveRecord $record)
{
	$uid = $user->uid;

	if ($uid == 1 || (!empty($record->uid) && $record->uid == $uid))
	{
		return true;
	}
}

所有权解析器在 users 配置中的 ownership_resolver_list 数组中定义。它可以是函数或实现 OwnershipResolverInterface 接口的类的名称。

<?php

// …/config/users.php

return [

	'ownership_resolver_list' => [

		'a_resolver' => 'my_ownership_resolver',
		'another_resolver' => 'MyOwnershipResolverClass'

	]

];

解析器权重

可以使用 weight 键为每个解析器指定一个权重。这个权重可以是数值，如 -10 和 10，特殊值 top 和 bottom，或者相对于另一个解析器的位置，如 before:<resolver_id> 和 after:<resolver_id>，其中 <resolver_id> 是另一个解析器的标识符。

<?php

// users.roles/config/users.php

namespace Icybee\Modules\Users\Roles;

return [

	'permission_resolver_list' => [

		'roles' => [ PermissionResolver::class, 'weight' => 0 ]

	],

	'ownership_resolver_list' => [

		'roles' => [ OwnershipResolver::class, 'weight' => 10 ]

	]

];

在以下配置中，-10 的权重允许 "mymodule" 定义的权限解析器在 "roles" 定义的解析器之前。使用相对权重 before:roles，"mymodule" 的所有者解析器将被置于 "roles" 定义的解析器之前。

<?php

// mymodule/config/users.php

namespace App\Modules\MyModule;

return [

	'permission_resolver_list' => [

		'mymodule' => [ PermissionResolver::class, 'weight' => -10 ]

	],

	'ownership_resolver_list' => [

		'mymodule' => [ OwnershipResolver::class, 'weight' => 'before:roles' ]

	]

];

调用解析器

要确定用户是否具有特定权限，解析器将依次调用，以修改权限值，该值最初设置为 false。如果解析器返回的不是 null，则修改值。解析器通常只在授予权限时返回 true，否则返回 null。实际上，解析器只有在想要覆盖先前解析器的响应时才返回 false。

相同的流程用于确定用户是否是记录的所有者。

安全

防止暴力登录

为了防止暴力登录，每次失败的尝试都会记录在目标用户账户的元信息中。当失败尝试的数量达到限制（例如 10）时，用户账户将被锁定，并将带有解锁键的消息发送到用户的电子邮件地址。

一旦消息发送，接下来的连接请求将在一个小时之内失败。在此延迟之后，计数器将被重置。

以下元属性用于此过程

• (int) failed_login_count：连续失败的尝试次数。当用户成功登录时重置。
• (int) failed_login_time：上次失败的登录时间。
• (string) login_unlock_token：通过电子邮件发送给用户以解锁账户的密钥的盐化派生令牌。
• (int) login_unlock_time：解锁登录的时间。

需求

此包需要 PHP 5.5 或更高版本。

安装

安装此包的推荐方式是通过 Composer。

$ composer require icybee/module-users

此模块是 Icybee 所需模块的一部分。

克隆存储库

该包可在 GitHub 上找到，可以使用以下命令行克隆其存储库

$ git clone https://github.com/Icybee/module-users.git users

文档

该包作为 Icybee CMS 的文档的一部分进行文档编制。可以使用 make doc 命令生成包及其依赖项的文档。使用 ApiGen 在 docs 目录中生成文档。可以使用 make clean 命令清理包目录。

测试

使用 make test 命令运行测试套件。需要全局可用的 PHPUnit 和 Composer 才能运行套件。该命令将按需安装依赖项。运行测试套件并创建 "build/coverage" 中的 HTML 覆盖率报告的命令是 make test-coverage。可以使用 make clean 命令清理目录。

该包由 Travis CI 持续测试。

许可协议

icybee/module-users 在新BSD许可证下授权 - 有关详细信息，请参阅 LICENSE 文件。