PHP 串接新浪微博 OAuth2 登入 (Web 應用模式) 完整實作指南

新浪微博開放平台採用 OAuth 2.0 授權碼模式。本文從申請應用、配置回調、獲取 Authorization Code、換取 Access Token、獲取用戶資料、錯誤處理、Token 刷新與儲存，提供完整 PHP 實作範例，基於官方 PHP SDK (saetv2.ex.class.php) 並補充現代最佳實踐。

前置準備

1. 註冊微博開放平台開發者帳號，建立「網頁應用」。
2. 獲取 App Key (Client ID) 與 App Secret (Client Secret)。
3. 設定授權回調頁 (Callback URL)，必須為 HTTPS、完整路徑 (如 `https://example.com/callback.php`)，且域名需通過 ICP 備案。
4. 下載官方 PHP SDK：easywechat/weibo (現代維護版) 或舊版 saetv2.ex.class.php。

配置檔 (config.php)

<?php
return [
    'weibo' => [
        'client_id'     => 'YOUR_APP_KEY',
        'client_secret' => 'YOUR_APP_SECRET',
        'redirect_uri'  => 'https://yourdomain.com/callback.php', // 必須與後台一致
        'scope'         => 'all', // 或指定 scope: 'statuses_to_me_read,users_show_read'
    ],
];
?>

步驟 1：引導用戶授權 (login.php)

<?php
require_once 'vendor/autoload.php'; // Composer 載入 easywechat/weibo
$config = require 'config.php';

$app = \EasyWeChat\Weibo\Application::create($config['weibo']);
$oauth = $app->oauth;

// 生成授權 URL (state 參數防 CSRF)
$state = bin2hex(random_bytes(16));
$_SESSION['weibo_oauth_state'] = $state;

$authUrl = $oauth->getAuthorizationUrl($state);
// 產生類似：https://api.weibo.com/oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&state=...

echo "微博登入";
?>

步驟 2：回調頁處理授權碼、換取 Token (callback.php)

<?php
session_start();
require_once 'vendor/autoload.php';
$config = require 'config.php';

$app = \EasyWeChat\Weibo\Application::create($config['weibo']);
$oauth = $app->oauth;

// 1. 驗證 state 防 CSRF
if (empty($_GET['state']) || $_GET['state'] !== ($_SESSION['weibo_oauth_state'] ?? '')) {
    die('非法請求：State 不符合');
}
unset($_SESSION['weibo_oauth_state']);

// 2. 獲取授權碼
$code = $_GET['code'] ?? '';
if (empty($code)) {
    die('授權失敗：' . ($_GET['error_description'] ?? '用戶拒絕授權'));
}

try {
    // 3. 換取 Access Token
    $token = $oauth->getAccessToken($code);
    /*
    $token 結構：
    [
        'access_token'  => '2.00xxx',
        'expires_in'    => 157679999, // 秒
        'remind_in'     => 157679999,
        'uid'           => '1234567890', // 用戶 UID
        'isRealName'    => 'true',
    ]
    */

    // 4. 儲存 Token (資料庫/Redis/Session)
    // 建議儲存：uid, access_token, expires_at (time()+expires_in), refresh_token (若有)
    $_SESSION['weibo_user'] = [
        'uid'          => $token['uid'],
        'access_token' => $token['access_token'],
        'expires_at'   => time() + (int)$token['expires_in'],
    ];

    // 5. 導向會員中心或首頁
    header('Location: /member.php');
    exit;

} catch (\EasyWeChat\Kernel\Exceptions\InvalidArgumentException $e) {
    die('參數錯誤：' . $e->getMessage());
} catch (\EasyWeChat\Kernel\Exceptions\RuntimeException $e) {
    die('網路/服務器錯誤：' . $e->getMessage());
}
?>

步驟 3：獲取用戶資料 (member.php)

<?php
session_start();
require_once 'vendor/autoload.php';
$config = require 'config.php';

if (empty($_SESSION['weibo_user'])) {
    header('Location: login.php');
    exit;
}

$user = $_SESSION['weibo_user'];

// 檢查 Token 是否過期，需刷新
if ($user['expires_at'] < time()) {
    $app = \EasyWeChat\Weibo\Application::create($config['weibo']);
    $oauth = $app->oauth;
    // 微博不支援標準 Refresh Token，需引導用戶重新授權
    // 或使用官方提供的「延長有效期」API (需高級權限)
    header('Location: login.php');
    exit;
}

$app = \EasyWeChat\Weibo\Application::create($config['weibo']);
$app->setAccessToken($user['access_token']);

// 獲取用戶詳細資料
try {
    $profile = $app->user->show($user['uid']);
    /*
    $profile 結構：
    {
        "id": 1234567890,
        "screen_name": "用戶昵稱",
        "profile_image_url": "https://.../avatar.png",
        "gender": "m",
        "location": "北京 海淀區",
        "followers_count": 100,
        "friends_count": 50,
        "statuses_count": 200,
        "verified": true,
        "verified_type": 0,
        ...
    }
    */
} catch (\Exception $e) {
    die('獲取用戶資料失敗：' . $e->getMessage());
}
?>
<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>會員中心</title></head><body>
<h1>歡迎，</h1>
<img src="" alt="頭像">
<p>UID: </p>
<p>粉絲:  | 關注:  | 微博: </p>
<a href="logout.php">登出</a>
</body></html>

步驟 4：登出 (logout.php)

<?php
session_start();
session_destroy();
header('Location: /');
exit;
?>

Token 管理最佳實踐

常見錯誤碼對照

遷移建議：舊版 saetv2.ex.class.php → easywechat/weibo

• 舊版 SDK 早已停止維護，不支援 PHP 8、Composer、PSR-4、現代異步 HTTP。
• easywechat/weibo 積極維護、支援 Laravel/Lumen/原生 PHP、單元測試覆蓋、文件完善。
• 遷移核心：`new SaeTOAuth()` → `\EasyWeChat\Weibo\Application::create()`，`getAuthorizeURL()` → `$app->oauth->getAuthorizationUrl()`，`getAccessToken('code',...)` → `$app->oauth->getAccessToken($code)`。

小結

微博 OAuth2 登入核心流程：引導授權 → 回調換碼 → 儲存 Token → 獲取用戶資料。關鍵在於：State 參數防 CSRF、HTTPS 回調域名備案、Token 安全儲存與過期處理、使用現代 SDK (easywechat/weibo)。掌握此流程，即可快速接入微博開放平台的社交登入、分享、評論等能力。