README

简单易用的 OAuth

此 SDK 允许您从 PHP 后端使用 OAuth.io，以处理来自服务器的身份验证和 API 调用，而不是来自前端，支持 100 多个 API 提供商。

SDK 的当前版本为 0.3.2。旧版本已弃用。

您还可以通过检查我们的 develop 分支来获取夜间版本。

有关此 SDK 及其方法的更多信息，请参阅 OAuth.io 上的 参考文档。

特性

• 服务器端 OAuth 身份验证流程
• 后端 API 请求
• 当可用时，请求统一用户信息（.me() 方法）
• 当可用时，使用 refresh_token 更新访问令牌

常见用例

您不希望直接从前端使用 API，而是通过 PHP 后端的 Web 服务。

安装

首先，您需要在 OAuth.io 的 仪表板中将您的应用后端设置为 PHP。

这允许您从提供者处获取刷新令牌（如果可用）。

您可以通过在 composer.json 中添加以下依赖项来安装它：

 "require": {
        ...
        "oauth-io/oauth": "0.3.0"
        ...
    },

然后在控制台运行

$ composer install

使用 SDK

OAuth 类存储在 OAuth_io 命名空间中。您需要在文件中包含它，如下所示（请确保您已包含 Composer 自动加载器文件）

<?php

require_once '/path/to/autoload.php';

use OAuth_io\OAuth;

//?>

PSR-0 支持

如果您使用具有自动加载器的 Composer，则可以使用 PSR-0 语法来使用此软件包。只需将以下代码放在脚本顶部即可

<?php

use OAuth_io\OAuth;

//?>

初始化

要初始化 SDK，您必须提供 OAuth.io 应用程序的关键字和密钥（您可以在 oauth.io 密钥管理器上获取它们）

<?php
$oauth = new OAuth();
$oauth->initialize('your_key', 'your_secret');
//?>

关于会话的说明

您可以将自己的会话数组传递给构造函数，这样如果您已经有一个会话管理器，则 SDK 不会对其进行干预

<?php
$_SESSION['some_subarray_in_the_session'] = array();
$myarray = $_SESSION['some_subarray_in_the_session'];

$oauth = new OAuth($myarray);
//?>

关于证书的说明

如果您正在使用 oauthd（oauth.io 的开源版本）并且您还没有经过验证的 SSL 证书（如果您希望在将来将代码投入生产，则应该有），则可以像这样禁用 SSL 证书验证

<?php
$oauth = new OAuth(null, false);
//?>

用户认证

您需要做的第一件事是创建一个端点，将用户重定向到提供者的身份验证页面，以便用户可以接受您的应用程序所需的权限。

在此端点中，调用 redirect 方法，如下所示

$oauth->redirect('the_provider', '/callback/url');

这将自动将用户重定向到提供者的网站。一旦用户接受了权限，他们将被重定向到您的应用程序上的 '/callback/url'，在那里您可以检索请求对象。

在关联到 '/callback/url' 的端点中，使用 redirect 选项设置为 true 调用 auth 方法以获取请求对象，如下所示

$request_object = $oauth->auth('the_provider', array(
    'redirect' => true
));

$request_object 是一个对象，允许您执行请求（请参阅以下部分了解如何操作），并包含用户的凭证。

使用会话获取请求对象

通常，您希望在用户连接到您的应用程序期间多次调用API。一旦您使用代码验证了用户一次，会话将自动配置为与SDK一起工作。

因此，您只需这样做即可获取请求对象

$request_object = $oauth->auth('the_provider');

将凭证保存以重新生成请求对象

您还可以将用户的凭证保存到cron中以进行请求。您可以从如下请求对象中获取凭证数组

$credentials = $request_object->getCredentials();
// Here save the $credentials array for later use

然后，当您想重新使用这些凭证时，您可以从中重建一个 $request_object

$request_object = $oauth->auth('the_provider', array(
    'credentials' => $credentials
));

向API发送请求

一旦您有了请求对象，您就可以向API发送请求。

<?php
$response_GET = $request_object->get('https://theprovider.com/api/endpoint');

$response_POST = $request_object->post('https://theprovider.com/api/endpoint', array('some' => 'data'));
$response_PUT = $request_object->put('https://theprovider.com/api/endpoint', array('some' => 'data'));
$response_DELETE = $request_object->del('https://theprovider.com/api/endpoint');
$response_PATCH = $request_object->patch('https://theprovider.com/api/endpoint', array('some' => 'data'));
//?>

您还可以从该请求对象调用 me(array $filters) 方法。此方法返回包含有关用户信息的统一数组。

<?php
$facebook_requester = $oauth->auth('facebook', array(
    'redirect' => true
));

$result = $facebook_requester->me(array('firstname', 'lastname', 'email'));

// you'll have $result["firstname"], $result["lastname"] and $result["email"] set with the user's facebook information.
//?>

您可以参考OAuth.io me()功能以获取有关此方法返回的字段更多信息。

刷新令牌

如果刷新令牌可用且访问令牌已过期，auth 方法将自动使用该刷新令牌获取新的访问令牌。

您可以通过在选项数组中传递 force_refresh 字段强制更新

$request_object = $oauth->auth('the_provider', array(
    'credentials' => $credentials,
    'force_refresh' => true
));

您还可以直接这样刷新一个凭证数组

$refreshed_credentials = $oauth->refreshCredentials($old_credentials);

为这个SDK做贡献

问题

请将问题和功能讨论在Github Issues上。我们将很乐意回答您的问题并根据您的反馈改进SDK。

拉取请求

欢迎您fork并创建拉取请求。我们感谢您在这项工作上所花费的时间，我们很乐意审查您的代码，并在它带来良好改进的情况下合并它 :)

如果您想创建一个拉取请求，请注意以下简单的规则

• 每个拉取请求一个特性
• 编写清晰的提交信息
• 为您的特性编写单元测试：例如，如果您修复了一个bug，编写一个测试来证明bug的存在以及您的修复是如何解决它的。
• 编写清晰的拉取请求描述

如果您这样做，我们将能够更快地合并您的拉取请求 :)

SDK被编写为一个Composer模块。您可以通过以下方式安装其依赖项

sdk/folder$ composer install

测试SDK

我们使用PHPUnit来测试SDK。要从SDK根目录测试它，只需运行以下命令

$ ./vendor/phpunit/phpunit/phpunit

许可协议

该SDK在Apache2许可协议下发布。