PHP SDK · UserMatrix

安装

composer require yunjii/um-sdk

初始化

<?php
require 'vendor/autoload.php';

use Yunjii\UM\UM;

$um = new UM(
    'your_appid',                          // 应用 ID
    'your_appkey',                         // 应用密钥
    'https://your-app.com/login/callback', // 回调地址
    'https://um.yunjii.cn/php'             // API 地址
);

API 地址默认为 https://um.yunjii.cn/php。如果是私有化部署，请改为你的服务器地址。

OAuth 2.0 完整流程

1. 生成登录跳转 URL

$state = bin2hex(random_bytes(16));
$_SESSION['oauth_state'] = $state;

$loginUrl = $um->login('wx', $state);
// => https://um.yunjii.cn/php/connect.php?act=login&appid=...&type=wx&...

header("Location: $loginUrl");

支持的平台类型：wx（微信）、alipay（支付宝）、qq（QQ）、douyin（抖音）、self（自有站）。

2. 回调处理

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

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

// 用 code 换取用户信息
$user = $um->callback($code);
// => [
//   "openid"     => "oX...",
//   "nickname"   => "张三",
//   "avatar"     => "https://...",
//   "social_uid" => "um_abc123",
//   "login_type" => "wx"
// ]

同一 code 5 分钟内只能消费一次，重复消费会返回 40163 错误。这是 UM 的防重放机制。

3. 二次查询（无需重新走 OAuth）

// 通过 social_uid 直接查询用户信息
$info = $um->query('wx', $social_uid);

Token 验证

// 验证用户 Token（用于 API 鉴权）
$result = $um->checkToken($token);
if ($result['code'] === 1) {
    $userId = $result['data']['user_id'];
    $scope  = $result['data']['scope']; // app / group / global
}

错误处理

try {
    $user = $um->callback($code);
} catch (\Yunjii\UM\UMException $e) {
    echo $e->getErrCode();  // 错误码（如 40163）
    echo $e->getMessage();  // 错误信息
}

高级配置

自定义登录策略

// 配置分组 SSO（同组应用共享登录态）
$um->setPolicy('group_sso', [
    'group_key'   => 'yunjii_products',
    'max_devices' => 3,
]);

多设备管理

// 查询用户在线设备
$devices = $um->getDevices($token);

// 强制下线指定设备
$um->kickDevice($token, $deviceId);

完整示例

详见 GitHub 仓库的 examples/ 目录。