README

本包为 PHP League 的 OAuth 2.0 客户端提供了 Facebook OAuth 2.0 支持。

本包符合 PSR-1、PSR-2、PSR-4 和 PSR-7 规范。如果发现不符合规范的地方，请通过 pull request 发送补丁。

要求

以下版本的 PHP 受支持。

PHP 7.3
PHP 7.4
PHP 8.0

安装

将以下内容添加到您的 composer.json 文件中。

{
    "require": {
        "league/oauth2-facebook": "^2.0"
    }
}

使用方法

授权码流

session_start();

$provider = new \League\OAuth2\Client\Provider\Facebook([
    'clientId'          => '{facebook-app-id}',
    'clientSecret'      => '{facebook-app-secret}',
    'redirectUri'       => 'https://example.com/callback-url',
    'graphApiVersion'   => 'v2.10',
]);

if (!isset($_GET['code'])) {

    // If we don't have an authorization code then get one
    $authUrl = $provider->getAuthorizationUrl([
        'scope' => ['email', '...', '...'],
    ]);
    $_SESSION['oauth2state'] = $provider->getState();
    
    echo '<a href="'.$authUrl.'">Log in with Facebook!</a>';
    exit;

// Check given state against previously stored one to mitigate CSRF attack
} elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {

    unset($_SESSION['oauth2state']);
    echo 'Invalid state.';
    exit;

}

// Try to get an access token (using the authorization code grant)
$token = $provider->getAccessToken('authorization_code', [
    'code' => $_GET['code']
]);

// Optional: Now you have a token you can look up a users profile data
try {

    // We got an access token, let's now get the user's details
    $user = $provider->getResourceOwner($token);

    // Use these details to create a new profile
    printf('Hello %s!', $user->getFirstName());
    
    echo '<pre>';
    var_dump($user);
    # object(League\OAuth2\Client\Provider\FacebookUser)#10 (1) { ...
    echo '</pre>';

} catch (\Exception $e) {

    // Failed to get user details
    exit('Oh dear...');
}

echo '<pre>';
// Use this to interact with an API on the users behalf
var_dump($token->getToken());
# string(217) "CAADAppfn3msBAI7tZBLWg...

// The time (in epoch time) when an access token will expire
var_dump($token->getExpires());
# int(1436825866)
echo '</pre>';

FacebookUser 实体

当使用 getResourceOwner() 方法获取用户节点时，它将以 FacebookUser 实体的形式返回。

$user = $provider->getResourceOwner($token);

$id = $user->getId();
var_dump($id);
# string(1) "4"

$name = $user->getName();
var_dump($name);
# string(15) "Mark Zuckerberg"

$firstName = $user->getFirstName();
var_dump($firstName);
# string(4) "Mark"

$lastName = $user->getLastName();
var_dump($lastName);
# string(10) "Zuckerberg"

# Requires the "email" permission
$email = $user->getEmail();
var_dump($email);
# string(15) "[email protected]"

# Requires the "user_hometown" permission
$hometown = $user->getHometown();
var_dump($hometown);
# array(10) { ["id"]=> string(10) "12345567890" ...

# Requires the "user_about_me" permission
$bio = $user->getBio();
var_dump($bio);
# string(426) "All about me...

$pictureUrl = $user->getPictureUrl();
var_dump($pictureUrl);
# string(224) "https://fbcdn-profile-a.akamaihd.net/hprofile- ...

$isDefaultPicture = $user->isDefaultPicture();
var_dump($isDefaultPicture);
# boolean false

$coverPhotoUrl = $user->getCoverPhotoUrl();
var_dump($coverPhotoUrl);
# string(111) "https://fbcdn-profile-a.akamaihd.net/hphotos- ...

$gender = $user->getGender();
var_dump($gender);
# string(4) "male"

$locale = $user->getLocale();
var_dump($locale);
# string(5) "en_US"

$timezone = $user->getTimezone();
var_dump($timezone);
# int -5

$link = $user->getLink();
var_dump($link);
# string(62) "https://www.facebook.com/app_scoped_user_id/1234567890/"

$maxAge = $user->getMaxAge();
var_dump($maxAge);
# int 17 | null

$minAge = $user->getMinAge();
var_dump($minAge);
# int 21

您也可以使用 toArray() 方法以纯 PHP 数组的格式获取用户节点的所有数据。

$userData = $user->toArray();

Graph API 版本

需要设置 graphApiVersion 选项。如果未设置，将抛出 \InvalidArgumentException 异常。

$provider = new League\OAuth2\Client\Provider\Facebook([
    /* . . . */
    'graphApiVersion'   => 'v2.10',
]);

Graph API 的每个版本之间都有破坏性的更改。此包不再支持回退到默认的 Graph 版本，因为当回退的 Graph 版本更新时，您的应用可能会出现问题。

有关更多信息，请参阅 Graph API 版本计划。

测试版层

Facebook 有一个测试版层，其中包含在它们投入生产之前的最新的部署。要启用测试版层，将 enableBetaTier 选项设置为 true。

$provider = new League\OAuth2\Client\Provider\Facebook([
    /* . . . */
    'enableBetaTier'   => true,
]);

刷新令牌

Facebook 不支持刷新令牌。为了获取新的“刷新”令牌，您必须再次通过 Facebook 登录流程将用户发送过去。

来自 Facebook 文档

一旦 [访问令牌] 过期，您的应用必须再次将用户通过登录流程发送过去以生成一个新的短期令牌。

以下代码将抛出 League\OAuth2\Client\Provider\Exception\FacebookProviderException。

$grant = new \League\OAuth2\Client\Grant\RefreshToken();
$token = $provider->getAccessToken($grant, ['refresh_token' => $refreshToken]);

长期访问令牌

Facebook 允许您通过使用短期访问令牌交换长期访问令牌来延长访问令牌的有效期。

一旦您获得了一个短期（默认）访问令牌，您就可以将其交换为长期访问令牌。

try {
    $token = $provider->getLongLivedAccessToken('short-lived-access-token');
} catch (Exception $e) {
    echo 'Failed to exchange the token: '.$e->getMessage();
    exit();
}

var_dump($token->getToken());
# string(217) "CAADAppfn3msBAI7tZBLWg...

获取更多数据

一旦您获取了用户访问令牌，您可以使用您的喜欢的 HTTP 客户端发送额外的请求到 Graph API。在这个例子中，我们将只使用 PHP 内置的 file_get_contents() 作为我们的 HTTP 客户端来获取认证用户的前 5 个活动。

// Get 5 events from authenticated user
// Requires the `user_events` permission
$baseUrl = 'https://graph.facebook.com/v2.10';
$params = http_build_query([
    'fields' => 'id,name,start_time',
    'limit' => '5',
    'access_token' => $token->getToken(),
    'appsecret_proof' => hash_hmac('sha256', $token->getToken(), '{facebook-app-secret}'),
]);
$response = file_get_contents($baseUrl.'/me/events?'.$params);

// Raw JSON response from the Graph API
var_dump($response);
# string(1190) "{"data":[{"id":"123","name":"Derby City Swing 2016","start_time":"2016-01-28T17:00:00-0500"} ...

// Response as a plain-old PHP array
$data = json_decode($response, true);
var_dump($data);
# array(2) { ["data"]=> array(5) { ...

更多信息请参阅

如果您需要向 Graph API 发送更复杂的查询以通过一次请求获取大量数据，请查看 Facebook 查询构建器。

测试

$ ./vendor/bin/phpunit

league / oauth2-facebook

维护者

详细信息