UserMatrix

安装

UM PHP SDK 是单文件 SDK，直接引入即可，无需 composer：

# 从 /php/sdk/ 目录获取 UM.class.php
cp /php/sdk/UM.class.php your-project/lib/

初始化

<?php
require_once 'lib/UM.class.php';

$um = new UM(
    'your_appid',                          // 应用 ID（控制台获取）
    'your_appkey',                         // 应用密钥（控制台获取）
    'https://your-app.com/callback.php',   // 回调地址
    'https://um.yunjii.cn/'                // API 根地址（默认）
);

API 根地址默认为 https://um.yunjii.cn/。私有化部署请改为你的服务器地址。在 um.yunjii.cn/console/apps 创建应用获取 appid/appkey。

OAuth 2.1 + PKCE 完整流程

1. 生成授权 URL

session_start();

$state    = bin2hex(random_bytes(16));
$verifier = $um->generateCodeVerifier();           // PKCE code_verifier
$_SESSION['oauth_state']    = $state;
$_SESSION['oauth_verifier'] = $verifier;

$authUrl = $um->authorizeUrl($state, $verifier);   // 自动计算 code_challenge (S256)
// => https://um.yunjii.cn/oauth/authorize.php?response_type=code&client_id=...&code_challenge=...&...

header('Location: ' . $authUrl);

2. 回调处理（code 换 token）

session_start();

$state = $_GET['state'] ?? '';
$code  = $_GET['code']  ?? '';

// 防 CSRF
if ($state !== $_SESSION['oauth_state']) {
    throw new Exception('State mismatch');
}

// 用 code + code_verifier 换取 access_token
$tokenRes = $um->token($code, $_SESSION['oauth_verifier']);
if (empty($tokenRes['access_token'])) {
    die('换取 token 失败：' . $tokenRes['msg']);
}

// $tokenRes 结构：
// [
//   'code'          => 0,
//   'access_token'  => 'eyJ...',
//   'token_type'    => 'Bearer',
//   'expires_in'    => 604800,
//   'refresh_token' => 'rt_xxx...',
//   'user'          => ['id'=>123, 'openid'=>'um_xxx', 'nickname'=>'张三', ...]
// ]

// 清理 PKCE 临时数据
unset($_SESSION['oauth_state'], $_SESSION['oauth_verifier']);

// 存储 token（建议存 session 或数据库）
$_SESSION['access_token']  = $tokenRes['access_token'];
$_SESSION['refresh_token'] = $tokenRes['refresh_token'];

同一 code 5 分钟内只能消费一次，重复消费返回 errcode=40163。

3. 获取用户信息（OIDC UserInfo）

$user = $um->userinfo($tokenRes['access_token']);
// => [
//   'sub'                => 'um_a1b2c3d4e5f6',   // UMID，跨应用唯一
//   'name'               => '张三',
//   'nickname'           => '张三',
//   'picture'            => 'https://...',
//   'email'              => 'zhangsan@example.com',
//   'email_verified'     => true,
//   'login_type'         => 'wx',
//   'iss'                => 'https://um.yunjii.cn',
//   ...
// ]

4. 刷新 Token（轮换制）

$newToken = $um->refreshToken($_SESSION['refresh_token']);
// => ['code'=>0, 'access_token'=>'新', 'refresh_token'=>'新', ...]

// ⚠️ 旧 refresh_token 已失效，必须更新为新的
$_SESSION['access_token']  = $newToken['access_token'];
$_SESSION['refresh_token'] = $newToken['refresh_token'];

5. 撤销 Token（登出）

$um->revoke($_SESSION['access_token'], 'access_token');
$um->revoke($_SESSION['refresh_token'], 'refresh_token');
session_destroy();

扫码登录（二维码图片）

适合 PC 端场景，直接 <img> 引用二维码 URL：

$qrUrl = $um->qrcodeUrl('wx', 200, 'state-xyz');
// => https://um.yunjii.cn/api/qrcode.php?appid=...&type=wx&size=200&...

echo '<img src="' . htmlspecialchars($qrUrl) . '" width="200" height="200" alt="登录二维码">';

用户扫码后 UM 按 redirect_uri 回调 code，后续走上面的「回调处理」。

支持的 type：page（默认）/ wx / alipay / qq / douyin / self。

Client Credentials（机器到机器）

家族产品互联、无用户上下文的服务间调用：

$token = $um->clientCredentials('app');
// => ['code'=>0, 'access_token'=>'eyJ...', 'expires_in'=>604800]

错误处理

$tokenRes = $um->token($code, $verifier);
if ($tokenRes['code'] !== 0) {
    $errcode = $tokenRes['errcode'] ?? 'unknown';
    $msg     = $tokenRes['msg'] ?? '未知错误';
    error_log("UM OAuth error: [$errcode] $msg");
    // 常见错误码：
    //   101 = 参数错误
    //   102 = 应用不存在/状态异常
    //   103 = client_secret 不正确
    //   104 = code 不存在/未授权/已过期
    //   107 = PKCE code_verifier 校验失败
    //   108 = 服务端强制 PKCE 但缺少 code_challenge
    //   40163 = code 重复消费
}

完整示例

详见 GitHub 仓库的 examples/example.php，或直接查看 SDK 目录的可运行示例。

PHP SDK

安装

初始化