README

     _                 _                           _
 ___(_)_ __ ___  _ __ | | ___  _ __     __ _ _ __ | |_   _ ___
/ __| | '_ ` _ \| '_ \| |/ _ \| '_ \   / _` | '_ \| | | | / __|
\__ \ | | | | | | |_) | | (_) | | | | | (_| | |_) | | |_| \__ \
|___/_|_| |_| |_| .__/|_|\___/|_| |_|  \__, | .__/|_|\__,_|___/
                |_|                    |___/|_|

Simplon/Gplus

1. 安装
2. 设置 Gplus 模块
   2.1 创建认证容器
   2.2 创建 Gplus 模块实例
3. 用法
   3.1 请求认证 URL
   3.2 请求 AccessToken
   3.3 读取用户资料数据
   3.4 手动刷新 AccessToken
4. 完整示例

依赖项

• PHP >= 5.4
• CURL

1. 安装

通过 composer 安装 easy

{
  "require": {
    "simplon/gplus": "0.0.*"
  }
}

2. 设置 Gplus 模块

对于我们要进行的所有调用，我们需要使用我们的 Google Api 凭据 来初始化我们的 Gplus 模块。如果您没有这些凭据，请转到 Google 控制台 并创建它们。

2.1 创建认证容器

我们使用一个 值对象 来保存我们的凭据。我喜欢值对象，因为它们可以清楚地传达它们持有的数据类型。

$authVo = (new \Simplon\Gplus\Vo\GplusAuthVo())
    ->setClientId(CLIENT_ID)
    ->setClientSecret(CLIENT_SECRET)
    ->setUrlRedirect(AUTH_URL_REDIRECT); // URL to which google redirects after authentication

强制认证提示： 默认情况下，Google 会自动判断是否需要批准您的应用程序。这意味着用户第一次将看到提示，而在第二次时，用户将直接重定向到给定的 AUTH_URL_REDIRECT。

为了测试目的，我发现强制在认证时出现提示非常理想。要启用此功能，以下设置应该可以正常工作

$authVo = (new \Simplon\Gplus\Vo\GplusAuthVo())
    ->setClientId(CLIENT_ID)
    ->setClientSecret(CLIENT_SECRET)
    ->setUrlRedirect(AUTH_URL_REDIRECT);
    ->forceApprovalPrompt();

2.2 创建 Gplus 模块实例

好的，现在我们已经有了我们的 GplusAuthVo，我们可以继续创建我们的 Gplus 实例。

// pass our prior created authVo
$gplus = new \Simplon\Gplus\Gplus($authVo);

3. 用法

此场景显示了通过服务器初始化的认证流程。如果您已经有了 accessToken 和 refreshToken，您可以直接跳到 3.3。

记住： 我们需要之前创建的 Gplus 实例 $gplus 才能与 Google 的 API 交互。

3.1 请求认证 URL

我们需要一个 认证 URL，我们可以将其传递给一个 Web 客户端，该客户端再将用户重定向到 Google 的认证过程。

对于此示例，我们将请求访问用户的 电子邮件 和其 资料数据。 注意： 在以下示例中，我使用一组 类常量，这有助于我避免输入错误等。我建议您也这样做，因为它有助于您在代码中跟踪数据。

// with class constants (highly recommended)
$scopes = [
    \Simplon\Gplus\GplusConstants::AUTH_SCOPE_EMAIL,
    \Simplon\Gplus\GplusConstants::AUTH_SCOPE_PROFILE,
];

// without class constants
$scopes = ['email', 'profile',];

现在，让我们获取 认证 URL。此 URL 应传递给 Web 客户端，该客户端应将其打开。我们还需要告诉 Google 我们请求哪些权限。以下是一份 可能的权限列表。

// pass prior defined $scopes
$urlAuth = $gplus->getAuthUrl($scopes);

3.2 请求 AccessToken

如果一切顺利，Google 将重定向到之前定义的 AUTH_URL_REDIRECT，并在 URL 中附加一个名为 code 的 GET 参数。我们将使用此代码来将其交换为有效的 accessToken。

if(isset($_GET['code']))
{
    $gplusRequestAccessTokenVo = $gplus->requestAccessToken($_GET['code']);
    
    if($gplusRequestAccessTokenVo !== FALSE)
    {
        echo $gplusRequestAccessTokenVo->getAccessToken();
        echo $gplusRequestAccessTokenVo->getRefreshToken();
    }
}

如果一切顺利，我们将通过 $gplusRequestAccessTokenVo 接收一些数据，这是一个另一个值对象。实际上，我们主要对两个变量感兴趣： accessToken 和其 refreshToken。

accessToken 将为我们提供访问请求的 权限，而 refreshToken 将在 accessToken 生命周期结束时（2 小时）更新 accessToken。因此，保存这两个令牌并且永远不要丢失 refreshToken 非常重要。

3.3 读取用户资料数据

为了读取用户的资料数据，我们需要上述令牌

$gplusPersonVo = $gplus->getUserDetails($accessToken, $refreshToken);

如果调用成功，您将收到一个包含所有基本资料数据的 GplusPersonVo。

$gplusPersonVo->getAccessToken();
$gplusPersonVo->getDisplayName();
$gplusPersonVo->getEmailAccount();
$gplusPersonVo->getEmails();
$gplusPersonVo->getGender();
$gplusPersonVo->getId();
$gplusPersonVo->getLanguage();
$gplusPersonVo->getRefreshToken();
$gplusPersonVo->getUrlImage();
$gplusPersonVo->getUrlImageBySize($squareSizePixel = 50);
$gplusPersonVo->getUrlProfile();
$gplusPersonVo->getVerified();
$gplusPersonVo->isNewAccessToken();
$gplusPersonVo->isVerified();

仍然有一批数据未被访问，可以通过$gplusPersonVo->getRawData()作为数组访问。如果accessToken不再有效，该方法将自动尝试使用refreshToken来更新它。如果失败，您将收到一个GplusException。

3.4 手动刷新 AccessToken

为了获取新的accessToken，您应该调用以下方法。如果调用成功，您将收到GplusRefreshAccessTokenVo，其中包含新鲜accessToken - $gplusRefreshAccessTokenVo->getAccessToken()。

$gplusRefreshAccessTokenVo = $gplus->refreshAccessToken($refreshToken);

如果调用不成功，您将收到FALSE或一个GplusException。

4. 完整示例

以下是一个完整流程示例的详细描述。

// set credentials
$authVo = (new \Simplon\Gplus\Vo\GplusAuthVo())
    ->setClientId(CLIENT_ID)
    ->setClientSecret(CLIENT_SECRET)
    ->setUrlRedirect(AUTH_URL_REDIRECT);
    
// create instance
$gplus = new \Simplon\Gplus\Gplus($authVo);

// set permission scopes
$scopes = [
    \Simplon\Gplus\GplusConstants::AUTH_SCOPE_EMAIL,
    \Simplon\Gplus\GplusConstants::AUTH_SCOPE_PROFILE,
];

// get auth url
$urlAuth = $gplus->getAuthUrl($scopes);

// --> redirect user to Google's authentication page

// ##############################################

// <-- user comes back with code ...

if(isset($_GET['code']))
{
    // get accessToken + refreshToken
    $gplusRequestAccessTokenVo = $gplus->requestAccessToken($_GET['code']);
    
    if($gplusRequestAccessTokenVo !== FALSE)
    {
        // --> save accessToken + refreshToken for offline access to DB ...
        
        // fetch profile data
        $gplusPersonVo = $gplus->getUserDetails(
            $gplusRequestAccessTokenVo->getAccessToken(),
            $gplusRequestAccessTokenVo->getRefreshToken()
        );
        
        // print data
        var_dump($gplusPersonVo);
    }
}

许可证

Cirrus可以在MIT许可证的条款下自由分发。

版权（c）2014 Tino Ehrich（《opensource@efides.com》）

在此特此授予任何人免费获取本软件及其相关文档文件（以下简称“软件”）的副本的权利，不受任何限制地处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许向获得软件副本的人提供这样做，前提是遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途的适用性和非侵权性保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论该索赔、损害或其他责任是由于合同、侵权或其他方式引起的，与软件或软件的使用或任何其他方式有关。