palladium
Who is that "index" and where to find it
（正在进行中：2.0 的文档）
用于处理用户识别的库。
该库的目的是为给定的身份证明找到用户的帐户（准确地说是其唯一的 ID）并管理各种类型的身份。它由 4 种不同的服务组成：识别、注册、搜索和恢复。
您可以使用 Composer 通过以下命令将库添加到您的项目中：
composer require teresko/ palladium要使用此包，需要 PHP 版本 7.0+ 和 PDO。
您还需要创建一个表来存储身份。示例架构可在此处获取。它当前仅包含 MySQL/MariaDB 的表定义，但该库可与任何具有 PDO 驱动程序的 RDBMS 一起使用。
palladium包含 4 项服务： Registration 、 Identification 、 Search和Recovery 。这些服务中的每一个都有两个强制依赖项：
palladium ContractCanPersistIdenity ）PsrLogLoggerInterface ）如果您想要更改或替换持久性抽象层的部分内容，这将为您提供替换默认存储库的选项。至于记录器 - 推荐的方法是使用 Monolog，但它可以与任何兼容的日志系统一起使用。
默认存储库还具有添加自定义身份类型和数据映射器的功能，这些功能可用于您的或内置的身份类型。有关使用详细信息，请参阅 %TODO% 部分。
在Identification服务的构造函数中，有一个可选的第三个和第四个参数：
在Registration服务的构造函数中，有一个可选的第三个参数：
如上所述，所有 4 个服务都需要一个存储库作为构造函数依赖项。如果您不使用您的客户版本替换捆绑存储库，那么您将需要初始化palladium RepositoryIdentity并将其传递给服务。
捆绑的存储库本身有一个依赖项：实例，它实现palladium ContractCanCreateMapper 。该合约（接口）由palladium ComponentMapperFactory实现。这个工厂有两个依赖项： PDO实例和表的名称，其中将存储身份。
<?php
$ factory = new palladium Component MapperFactory ( new PDO (... $ config ), $ tableName );
$ repository = new palladium Repository Identity ( $ factory );在每个其他代码示例中，当您看到使用$repository变量时，您可以假设它已使用此代码示例进行初始化。
对于 Symfony 的 DependencyInjection 组件（版本：3.4+）的用户，有一个示例配置文件：%TODO%
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity );如果操作成功完成， $identity变量将包含未经验证的StandardIdentity实例。要完成验证，您必须使用身份包含的令牌。在给定的示例中，可以使用$instance->getToken()评估此令牌。
如果电子邮件已用于另一个身份，则createStandardIdentity()方法可能会引发IdentityConflict异常。
createStandardIdentity()方法有一个可选的第三个参数，用于定义电子邮件验证令牌的生命周期（以秒为单位）。应用后，前面的示例如下所示：
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' , 3600 );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity );这将使验证令牌在该用户的身份注册后 1 小时内可用。在给定的时间过后，您将无法使用Search服务中的findStandardIdentityByToken()找到此身份。
重要提示：
createStandardIdentity()方法不会验证用户电子邮件或任何其他类型的标识符。它仅检查其唯一性。电子邮件、电话号码、昵称和其他标识符的验证超出了该库的范围。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByToken ( $ token , palladium Entity Identity:: ACTION_VERIFY );
$ registration -> verifyStandardIdentity ( $ identity ); $token值用于查找匹配的EmailIdentity ，然后对其进行验证。如果未找到身份， findStandardIdentityByToken()将抛出IdentityNotFound异常。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ cookie = $ identification -> loginWithPassword ( $ identity , $ password );如果没有找到与给定标识符（例如电子邮件地址）匹配的身份，则findStandardIdentityByIdentifier()方法将抛出IdentityNotFound异常。
如果密码不匹配， loginWithPassword()方法将抛出PasswordMismatch异常。
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId );这将创建一个NonceIdentity的新实例。要使用它进行登录，您将需要NonceIdentity::getIdentifier()和NonceIdentity::getKey()中的值，其中标识符将用于定位随机数身份，密钥将用于验证。
createNonceIdentity()方法是可选的第二个参数，它定义了此一次性身份的生命周期（以秒为单位）。应用后，前面的示例如下所示：
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId , 600 );这将使一次性身份在创建后可使用 10 分钟。经过允许的时间后，在Identification的useNonceIdentity()方法中传递此身份将导致抛出IdentityExpired异常。
<?php
$ identity = $ this -> search -> findNonceIdentityByIdentifier ( $ identifier );
$ cookie = $ this -> identification -> useNonceIdentity ( $ identity , $ key );如果没有找到与给定标识符（电子邮件地址、昵称等）匹配的身份，则findNonceIdentityByIdentifier()方法将抛出IdentityNotFound异常。
如果密码不匹配， useNonceIdentity()方法将抛出KeyMismatch异常。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ cookie = $ identification -> loginWithCookie ( $ identity , $ key );如果使用findCookieIdentity()未找到 cookie，则会抛出标准IdentityNotFound异常。可能的原因是 cookie 不再处于活动状态（例如用户注销）或 cookie 根本不存在。
如果 cookie 太旧， loginWithCookie()将产生IdentityExpired异常。
但loginWithCookie()方法也会产生CompromisedCookie异常。看到此异常可能表明 cookie 已被盗或用户从未收到新的 cookie 值。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> blockIdentity ( $ identity );这是处理可疑 cookie 的推荐方法，这些 cookie 可能会被盗，也可能不会被盗。这不适用于注销用户。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> logout ( $ identity , $ key );此操作将 cookie 标记为“已丢弃”。可以生成的例外列表与使用 cookie 登录部分中描述的例外列表相匹配。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity );如果没有找到与给定电子邮件地址匹配的身份， findStandardIdentityByIdentifier()方法将抛出IdentityNotFound异常。
当调用markForReset()时，必须为其提供一个已经过验证的StandardIdentity实例（否则，它有可能从您的应用程序中泄漏用户的私人信息）。如果不是这种情况，该方法将抛出IdentityNotVerified异常。
markForReset()方法是可选的第二个参数，它定义密码重置令牌的生命周期（以秒为单位）。应用后，前面的示例如下所示：
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity , 7200 );这将使密码重置令牌在该用户的身份被标记为重置后的两个小时内可用。当允许的时间到期后，您将无法使用Search服务中的findEmailIdentityByToken()找到此身份。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findEmailIdentityByToken ( $ token , palladium Entity Identity:: ACTION_RESET );
$ recovery -> resetIdentityPassword ( $ identity , ' foobar ' );如果没有找到与给定令牌匹配的身份， findEmailIdentityByToken()方法将抛出IdentityNotFound异常。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ identification -> changePassword ( $ identity , $ oldPassword , $ newPassword );如果没有找到与给定电子邮件地址（或任何其他类型的标识符）匹配的身份，则findStandardIdentityByIdentifier()方法将抛出IdentityNotFound异常。
如果密码不匹配， changePassword()方法将抛出PasswordMismatch异常。
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ factory , $ logger );
$ list = $ search -> findIdentitiesByParentId ( $ identity -> getId ());
$ identification -> discardIdentityCollection ( $ list ); findIdentitiesByParentId()的返回值将返回IdentityCollection ，它可以为空。
如前所述，该库中的服务需要 PSR-3 兼容记录器作为依赖项。它将用于记录三个级别的事件：
LogLevel::INFO此日志级别用于跟踪用户在以预期方式使用应用程序时执行的普通操作：
LogLevel::NOTICE如果用户尝试执行不成功的操作，则将记录此级别的日志，这在正确的使用场景中不应发生：
LogLevel::WARNING仅用于当用户尝试使用受损 cookie 时的日志记录情况。
该库专注于一项特定任务。它不包含以下任何功能：
如果您认为该身份验证库需要上面列出的部分之一，那么这不是您正在寻找的库。
