README

Message\User cogule提供简单的用户和权限系统。

服务

待做：列出此处定义的服务

事件

以下事件由此cogule触发。事件对象始终是Message\User\Event\Event的实例。

• user.login.attempt：当尝试登录时触发（只有通过基本验证时），无论用户是否存在。此事件是Message\User\Event\LoginAttemptEvent的实例。
• user.login：当用户成功登录时触发。
• user.logout：当用户成功登出时触发。
• user.password.request：当请求重置密码时触发，只有当用户存在时。
• user.password.reset：当用户成功重置密码时触发。
  • 注意，如果通过“忘记密码”系统重置密码，则在触发此事件后，用户会登录，然后触发user.login事件。
• user.create：使用Message\User\Create装饰器创建用户时触发。
• user.edit：使用Message\User\Edit装饰器编辑用户时触发。
  • 以下情况下不会触发此事件：
    • 更新或清除“密码请求时间”。
    • 更新“最后登录时间”。
    • 将用户添加到或从组中删除。
• user.email_confirmed：当用户确认他们的电子邮件地址（如果需要）时触发。
• user.group.add：使用Message\User\Edit::addToGroup()将用户添加到组时触发。
• user.group.remove：使用Message\User\Edit::removeFromGroup()从组中删除用户时触发。

用户

用户具有以下属性

• 一个ID
• 一个电子邮件地址
• 一个“电子邮件已确认”标志
• 一个头衔（例如先生或女士）
• 一个名
• 一个姓
• 一个“最后登录”时间戳
• 一个“请求密码时间”时间戳

以及创建和更新的常规元数据。删除时没有元数据，因为当用户被删除时，他们是硬删除的：他们在数据库中不再存在。

如果您的应用程序或模块需要向用户添加更多属性，建议以有意义的方式分组这些属性，并创建一个新的模型来表示这些属性组。Message\User\User对象应该保持为基本用户信息的简单表示。

例如，在一个电子商务模块中，可能会为用户存储地址数据。在这种情况下，创建一个表示用户地址的模型会很有意义，如下所示

class UserAddress
{
	public $user;
	
	public $typeID;
	
	public $addressLines;
	public $town;
	public $postcode;
	public $countryID;
	public $stateID;
	public $telephone;
}

组

用户组当然是一种简单的用户分组方式。`Message\User` 模块本身不定义任何组，但它提供了组功能和一个框架，以便其他模块可以定义自己的组。

要定义一个组，首先需要创建一个实现了 `Message\User\Group\GroupInterface` 接口的类。

<?php

namespace Message\MyModule;

use Message\User\Group;

class SuperAdmin implements Group\GroupInterface
{
	/**
	 * {@inheritdoc}
	 */
	public function getName()
	{
		return 'super-admin';
	}

	/**
	 * {@inheritdoc}
	 */
	public function getDisplayName()
	{
		return 'Super Administrators';
	}

	/**
	 * {@inheritdoc}
	 */
	public function getDescription()
	{
		return 'Users with access to everything!';
	}

	/**
	 * {@inheritdoc}
	 */
	public function registerPermissions(Group\Permissions $permissions)
	{
		// ...
	}
}

然后只需将其添加到 `user.groups` 服务定义中，这是一个系统可用的用户组集合。未添加到此集合中的用户组对系统来说是“未知”的。

理想情况下，应在 `modules.load.success` 事件上添加组到集合中。在你的模块事件引导中添加如下的事件监听器：

$dispatcher->addListener('modules.load.success', function() use ($services) {
	$services['user.groups']
		->add(new Message\MyModule\SuperAdmin);
});

权限

此模块包含了一个简单的权限系统，它围绕用户组和路由集合或路由构建。

每个组都必须实现 `Message\User\Group\GroupInterface` 接口中定义的 `registerPermissions()` 方法。传递给此方法的参数是 `Message\User\Group\Permissions` 类的实例，适用于相应的组。

在 `registerPermissions()` 内部，可以为组注册一组权限。组可以授予以下权限之一：

• 特定路由集合中的所有路由。
• 特定的路由。
• 具有特定参数值的特定路由。

以下是所有三种情况的示例：

public function registerPermissions(Permissions $permissions)
{
	// Grants the group access to all routes in the 'my.collection' route collection
	$permissions
		->addRouteCollection('my.collection');
	
	// Grants the group access to the `homepage` and `secret.page` route
	$permissions
		->addRoute('homepage')
		->addRoute('secret.page');
	
	// Grants the group access to the `file.view` route only when the `type` parameter equals "image"
	$permissions
		->addRoute('file.view', array('type' => 'image'));
}

一旦任何组为路由或路由集合定义了权限，该路由或路由集合就变为“受保护”状态，除非当前用户所在的组有权访问该路由集合或特定路由，否则不可用。

如果当前用户没有访问受保护路由的适当权限，则会抛出 `Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException`。

控制器 & 路由

待办事项：撰写关于可用控制器和路由，以及如何在应用程序中使用它们的说明。