Auth 套件

Auth 套件在 Fuel 裡提供一个标准化的認證介面。 这使得我們的使用者能编寫自己的驅动程序，并且輕鬆地将新的驅动程序與舊的程式码整合， 以保持基本方法一致。

Auth_Login_Driver

此驅动是所有 Auth 登入驅动的基础类別。它被定義为一个抽象类別， 該类別包含了通用於所有登入驅动的所有方法， 以及定義給任何登入驅动必須實现的所有抽象方法。

驅动配置

一个登入驅动可以載入它所依賴的額外驅动。一般情況下，这些是 Group 驅动。 但你的實现情況可以是引進和使用自訂的驅动类型。要做到这一點，添加此結構到你的驅动类別： 

// 當載入此登入驅动時自动載入 Simplegroup 群組驅动
// 这也定義了此驅动有額外的使用者紀錄欄位 getter
	protected $config = array(
		'drivers' => array('group' => array('Simplegroup')),
		'additional_fields' => array('profile_fields'),
	);

靜態介面

为了易於使用，Auth 套件在登入驅动的公開方法提供一个靜態介面。 因为这个原因，登入基础驅动也定義 member() 和 has_access() 方法， 它提供了在群組和 ACL 驅动中靜態存取这些方法。

使用靜態介面，你能做到

// 回傳 'simpleauth'
$id = Auth::get_id();

來代替

// 回傳 'simpleauth'
$id = Auth::instance()->get_id();

这只在 Auth 配置中的 "verify_multiple_logins" 設为 false 時運作， 因为你不能對映一个靜態介面到多个活躍的登入驅动程序！

通用方法

通用方法被定義在登入基础驅动，而且能透過擴充到達所有的 Auth 登入驅动。这些方法提供功能來建立和取回實例、設定和取得配置值、 以及密码雜湊和對 ACL 和 Group 驅动存取的通用方法。

定義在类別中而沒記錄在此的方法是內部使用，而且不應該直接被呼叫。

get_id()

回傳驅动的唯一 ID。这可被用於識別驅动，或用來選擇一个特定的驅动實例。

靜態 否
參数 無
回傳 驅动 ID 字串。
範例 
// 回傳 'simpleauth'
$id = Auth::instance('simpleauth')->get_id();

set_config($key, $value)

設定一个驅动配置值。

靜態 否
參数
參数 預設 描述
$key 必要 配置鍵名
$value 必要 此配置鍵的值
回傳 空
範例 
// 設定一个配置值
Auth::instance()->set_config('key', 'value');

get_config($key, $default = null)

取得一个驅动配置值。

靜態 否
參数
參数 預設 描述
$key 必要 配置鍵名
$default null 如果請求的鍵不存在時要回傳的預設值
回傳 混合
範例 
// 取得一个配置值，如果不存在回傳 false
$key = Auth::instance()->get_config('key', false);

guest_login()

回傳是否驅动支援訪客登入（一个未認證的訪客使用者）。

靜態 否
參数 無
回傳 布林
範例 
// 檢查預設的實例是否支援訪客
if (Auth::instance()->guest_login())
{
	// 此驅动支援訪客登入！
}

預設情況下，此方法回傳 'false'。如果你的驅动有支援訪客登入， 在你的驅动类別中覆蓋載入此方法。

get_user_array(Array $additional_fields = array())

回傳一个描述目前登入使用者的陣列，總是包含至少一个顯示名稱和一个 email 地址。在驅动中可配置額外欄位或透過 陣列請求，但它們必須在該驅动內有一个 get_user_fieldname() 方法是可取得的。

靜態 否
參数
參数 預設 描述
$additional_fields array() 要取回的欄位名稱的陣列
回傳 陣列
範例 
// 在預設的實例呼叫此方法
$user = Auth::instance()->get_user_array();

// 在指定的實例呼叫此方法
$user = Auth::instance('simpleauth')->get_user_array();

// 靜態呼叫（如果 "verify_multiple_logins" 設为 false）
$user = Auth::get_user_array();

你可以在驅动配置陣列中定義 'additional_fields'，以在你呼叫此方法時让它們預設被包含。

hash_password($password)

回傳一个所給密码的 base64 编码雜湊值。此方法使用非常安全的 pbkdf2 雜湊演算法。

靜態 否
參数
參数 預設 描述
$password 必要 要雜湊的使用者密码
回傳 字串
範例 
// 雜湊一个使用者密码
$password = Auth::instance()->hash_password($password);

抽象方法

你所开发的每个登入驅动必須提供这些所有的方法，且必須回傳此处記錄的值。

perform_check()

內部类別方法用來檢查目前使用者是否有有效的 session。由你決定你的驅动要如何確定它。

靜態 否
參数 無
回傳 布林，true 如果有一个有效使用者 session，如果沒有則 false。

此方法是藉由 Auth::check() 呼叫，它不應該被应用程序直接呼叫。

validate_user()

validate_user 方法驗證一个登入請求。由你決定你的驅动要如何动作。

靜態 否
參数 無
回傳 混合。它應該回傳 false 如果使用者未通過驗證。任何被計算为 true 的值被認为是有效的。

如果它不是 false，应用程序不應假設關於回傳的值！

login()

login 方法执行一个登入請求。它應該呼叫 validate_user() 來驗證該請求。由你決定你的驅动要如何动作。

靜態 否
參数 無
回傳 布林。如果登入成功回傳 true，否則是 false。

如果你的驅动有支援訪客登入，它必須在回傳 false 之前設定該訪客。

logout()

logout 方法登出目前登入的使用者。由你決定你的驅动要如何动作。

靜態 否
參数 無
回傳 布林。如果登出成功回傳 true，否則是 false。

如果你的驅动有支援訪客登入，它必須在成功登出之後，設定該訪客为目前使用者。

get_user_id()

get_user_id 方法回傳包含驅动 ID 值和目前登入使用者 ID 的陣列結構。

靜態 否
參数 無
回傳 混合。如果使用者是登入的，回傳一个 array(driver_id, user_id) 形式的陣列，否則是 false。

如果你的驅动有支援訪客登入，它必須回傳有（虛擬）user_id 或你的訪客的陣列，而不是 false！

get_groups()

get_groups 方法回傳指派給資料者的使用者群組。

靜態 否
參数 無
回傳 混合。如果使用者是登入的，回傳一个 array(array(driver_id, group_id), array(driver_id, group_id), etc) 形式的陣列，否則是 false。

如果你的驅动有支援訪客登入，它必須回傳你的訪客使用者群組陣列，而非 false！

get_email()

get_email 方法回傳指派給目前登入的使用者 email 地址。

靜態 否
參数 無
回傳 混合。如果使用者登入回傳 email 地址，如果目前使用者沒有定義 email 地址，或使用者沒有登入回傳 false。

如果你的驅动有支援訪客登入，別忘了回傳 false 如果該訪客沒有定義一个 email 地址！

get_screen_name()

get_screen_name 方法回傳目前登入的使用者顯示名稱。

靜態 否
參数 無
回傳 混合。回傳包含名稱的字串，或 false 如果使用者沒有登入。

如果你的驅动有支援訪客登入，它必須回傳訪客顯示名稱，而非 false！