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 時的日誌記錄情況。
該庫專注於一項特定任務。它不包含以下任何功能：
如果您認為該身份驗證庫需要上面列出的部分之一，那麼這不是您正在尋找的庫。
