用法 - Opauth - Auth 套件

优质

小牛编辑

132浏览

2023-12-01

如同扩充 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(array $data)

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 中。