Opauth 用法

如同擴充 Auth 的 Opauth 简介 所言， 包裝类別自动配置自身为 Simpleauth 或 Ormauth，根據配置在 auth.php 配置档案中的驅动。

如果你不使用这些驅动，但已经在 Auth 框架中登記自己的驅动，你仍然可以使用 Opauth 整合类別， 但你不得不手动建立定義在 migration 008 的 'providers' 資料表。 你可以命名成任何你喜歡的。此外，你的自訂 Login 驅动應該提供 Auth::check()、 Auth::instance()->get_user_id()、Auth::instance()->force_login() 和 Auth::create_user() 方法，與 Simpleauth 原型相容。沒有这些，它不会運作。

执行階段配置

Opauth 大部分的配置已经透過 opauth.php 配置档案完成， 而且所有在該档案中的選項都可以在执行階段透過使用 $config 陣列傳遞一个新值到 forge() 來修改。此外， 有些配置值你只能在执行階段傳遞，他們不支援在配置档案中：

參数 类型 預設 描述
table 字串 
自动偵测
 允許你手动定義包含提供者資訊的資料表名稱。當使用 Simpleauth 或 Ormauth 時， 这个資料表的名稱是自动偵测的。如果你使用自訂的 Auth 驅动組，并已经手动建立資料表， 你将不得不在每次 forge 呼叫傳遞此資料表名稱。
path 字串 
自动偵测
 指向做你的 OAuth 認證的控制器方法的 URI 路徑。預設情況下， 它是設为在你鍛造一个 Opauth 物件時的目前路徑。
callback_url 字串 
自动偵测
 指向处理 OAuth 提供者回呼的控制器方法的 URI 路徑。預設情況下， 它是設为呼叫 path 指向的同一控制器中的 'action_callback' 或 'get_callback' 方法。
provider 字串 
自动偵测
 如果你已经手动設定 path，OAuth 提供者呼叫的自动偵测会失效， 而且你将不得不手动定義提供者名稱。这有區分大小寫，且必須與被策略提供者使用的字母， 以及在 opauth.php 配置档案中用來定義策略的鍵相符合。

當使用 Simpleauth 或 Ormauth，而且你已经在你的应用程序中遵循範例程式码整合 Opauth， 这些执行階段配置值都是不需要的，自动偵测值会做得很不错。

类別方法

forge($config = array(), $autorun = true)

forge 方法建立一个 Auth_Opauth 类別的實例，它提供 OAuth 與你的应用程序整合。

靜態 是
參数
參数 預設 描述
$config 
array()
 任何你想傳遞給該實例的执行階段配置值
$autorun 
true
 如果为 true，它会自动初始化一條到 OAuth 提供者的連線。如果为 false，它会只初始化該物件。
回傳 Auth_Opauth
範例 
/**
 * 載入包裝物件，并让它处理定義在 URI 中的提供者
 *
 * 这重導頁到提供者的認證頁面，所以它應該
 * 在你方法的最後一行
 */
\Auth_Opauth::forge();

// 鍛造一个有执行階段配置的物件
\Auth_Opauth::forge(array(
    'default_group' => $custom_group_id,
));

// 鍛造一个有执行階段配置的物件，來处理一个回呼
$opauth = \Auth_Opauth::forge(array(
    'default_group' => $custom_group_id,
), false);

如果你想要处理回呼而不傳遞自訂配置，你不必傳遞一个空陣列， 你可以使用 \Auth_Opauth::forge(false); 做为捷徑。

login_or_register()

login_or_register 方法处理提供者回呼。如果回傳的提供者 UID 是已知的， 使用者会使用與本地關聯的帳戶登入。如果不是，使用者会被要求註冊一个新帳戶， 或用已存在的帳戶登入并與其 UID 關聯。

靜態 否
參数 無
回傳 字串，狀態码。支援以下狀態码：
  • 'linked'：UID 成功連結到目前登入的使用者
  • 'logged_in'：使用者成功使用 OAuth 帳戶登入
  • 'registered'：UID 連結到新註冊的帳戶，并且使用者已登入
  • 'register'：UID 是未知的，并且沒有登入使用者存在，让使用者先註冊
範例 
// 取得 Opauth 物件
$opauth = \Auth_Opauth::forge(false);

// 嘗试使用提供者回呼資料來自动登入
$status = $opauth->login_or_register();

link_provider 方法能让你手动連結本地的使用者帳戶到 OAuth 登入。 你需要这个，如果你想为新使用者提供選項，首先註冊一个本地帳戶， 然後手动建立該帳戶與提供者 UID 的連結。

靜態 否
參数
參数 預設 描述
$data 
array()
 有全部所需用來建立連結（見範例）資料的陣列
回傳 混合。建立提供者連結紀錄的 insert id，或 false 如果建立失敗。
範例 
// 取得 opauth 物件
$opauth = \Auth_Opauth::forge(false);

// 我們有 OAuth 策略資料嗎？
if ($authentication = \Session::get('auth-strategy.authentication', array()))
{
	// 取得目前的 Auth userid
	list(, $userid) = \Auth::instance()->get_user_id();

	// 并連結到提供者
	$insert_id = $opauth->link_provider(array(
		'parent_id' => $userid,
		'provider' => $authentication['provider'],
		'uid' => $authentication['uid'],
		'access_token' => $authentication['access_token'],
		'secret' => $authentication['secret'],
		'refresh_token' => $authentication['refresh_token'],
		'expires' => $authentication['expires'],
		'created_at' => time(),
	));
}
else
{
	// 沒有可用的資料，看來我們沒收到先前 OAuth 的回呼？
}

get($key, $default = null)

get 方法是一个 getter， 允許直接存取由 Opauth 策略建立的原始提供者回呼的回應結構。

靜態 否
參数
參数 預設 描述
$key 必要 在回應陣列中期望值的鍵名稱
$default 
null
 如果請求的鍵不存在要回傳的預設值
回傳 混合。被所給鍵參照的值，或任何定義的 $default。
範例 
// 取得 opauth 物件
$opauth = \Auth_Opauth::forge(false);

// 取得一些 auth 資料
$provider = $opauth->get('auth.provider');
$uid = $opauth->get('auth.uid');
$token = $opauth->get('credentials.token', null);
$secret = $opauth->get('credentials.secret', null);
$expires = $opauth->get('credentials.expires', null);
$refresh_token = $opauth->get('credentials.refresh_token', null);

你只能在你处理回呼時使用此方法。在所有其他情況下， 沒有 OAuth 回應可用。如果先前有一个有效的回應处理， 其基本資料会使用 session 鍵 "auth-strategy" 儲存在 session 中。