YunXin Server SDK for PHP

网易云信服务端 PHP SDK。

✨ 核心特性

🚀 高性能与高可用

基于 Guzzle HTTP 客户端：成熟稳定的 HTTP 库，支持异步请求
多域名高可用：支持故障自动切换，保障服务连续性
智能服务器调度：动态端点选择，故障切换快速生效
灵活重试策略：内置多种重试策略，支持自定义重试逻辑

🔧 开发体验优化

双客户端模式：支持 Raw Client 和面向对象 Client 两种使用方式
完整类型支持：PHP 8+ 严格类型声明，IDE 友好的代码提示
TraceId 支持：完整的请求链路追踪，便于问题排查
Metrics 集成：支持 Prometheus 格式监控指标输出

📱 全业务模块覆盖

即时通讯 (IM)：用户管理、消息发送、群组管理等 V1/V2 API
实时音视频 (RTC)：房间管理、用户权限控制、AI 功能集成
短信服务 (SMS)：验证码发送、模板短信、批量发送
直播服务 (Live)：直播间管理、推拉流控制
点播服务 (VOD)：视频上传、转码、播放地址获取
房间组件 (Neroom)：教育场景房间管理
会议服务 (Meeting)：会议账号和房间管理

🏢 企业级部署支持

私有化环境：支持云信私有化部署环境
生产就绪：经过完整测试，72 个测试用例全部通过
PSR 标准：遵循 PSR-4 自动加载和 PSR-12 代码规范

📋 系统要求

PHP: 8.0+ （推荐 PHP 8.1+，已在 8.4 测试通过）
扩展: curl, json
依赖管理: Composer 2.0+
HTTP 客户端: Guzzle 7.0+

PHP 版本支持详情

✅ PHP 8.0+: 完全支持，所有功能可用
✅ PHP 8.1+: 推荐版本，性能更佳
✅ PHP 8.2+: 完全兼容
✅ PHP 8.3+: 完全兼容
✅ PHP 8.4: 已测试兼容
❌ PHP 7.4: 不支持（依赖包psr/log ^3.0要求PHP >= 8.0）

🔧 安装

使用 Composer 安装

composer require yunxin/server-sdk-php

手动安装

git clone https://github.com/netease-im/yunxin-server-sdk-php.git
cd yunxin-server-sdk-php
composer install

🚀 快速开始

基础用法 - 面向对象客户端

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

use YunxinServerSdk\Core\BizName;
use YunxinServerSdk\Core\YunxinApiHttpClient;
use YunxinServerSdk\Im\V2\YunxinV2ApiServices;
use YunxinServerSdk\Im\V2\Account\Request\CreateAccountRequestV2;

// 1. 创建 HTTP 客户端
$client = YunxinApiHttpClient::builderWithBizName(
    BizName::im(), 
    'your-app-key', 
    'your-app-secret'
)
->timeoutMillis(5000)
->build();

// 2. 创建业务服务
$v2Services = new YunxinV2ApiServices($client);
$accountService = $v2Services->getAccountV2Service();

// 3. 创建用户请求
$request = new CreateAccountRequestV2();
$request->setUsername('test_user_001');
$request->setNickname('测试用户');

// 4. 发起 API 调用
$result = $accountService->createAccount($request);

if ($result->isSuccess()) {
    $response = $result->getResponse();
    echo "用户创建成功，AccountId: " . $response->getAccountId() . "\n";
} else {
    echo "创建失败: " . $result->getMsg() . "\n";
}

基础用法 - Raw 客户端

<?php
use YunxinServerSdk\Core\Http\HttpMethod;

// 使用 Raw 客户端直接发送 HTTP 请求
$requestData = json_encode([
    'username' => 'test_user_001',
    'nickname' => '测试用户'
]);

$response = $client->executeJsonSimple(
    HttpMethod::POST,
    '/im/v2/accounts',
    null,
    $requestData
);

$data = json_decode($response->getData(), true);
echo "响应: " . json_encode($data, JSON_PRETTY_PRINT) . "\n";

📚 详细文档

快速开始指南

总体快速开始 - 项目概览和基础配置
IM V1 API - 即时通讯 V1 版本 API
IM V2 API - 即时通讯 V2 版本 API

业务模块文档

高级配置

端点管理 - 多域名配置和故障切换
重试机制 - 重试策略配置和自定义
监控指标 - Prometheus 指标集成
私有化部署 - 企业私有云配置
其他配置 - TraceId、超时设置等

🛠️ 开发与测试

环境准备

# 克隆项目
git clone https://github.com/netease-im/yunxin-server-sdk-php.git
cd yunxin-server-sdk-php

# 安装依赖
composer install

# 复制配置文件
cp phpunit.xml.dist phpunit.xml
# 编辑 .env 文件，填入测试用的 AppKey 和 AppSecret

运行测试

# 运行所有测试
composer test

# 运行指定测试
./vendor/bin/phpunit tests/BasicFunctionalityTest.php

# 生成测试覆盖率报告
composer test-coverage

代码质量检查

# 代码格式化 (PSR-12)
composer format

# 代码风格检查
composer lint

# 静态分析 (PHPStan Level 7)
composer analyze

目录结构

src/YunxinServerSdk/
├── Core/                   # 核心功能
│   ├── BizName.php        # 业务类型定义
│   ├── YunxinApiHttpClient.php  # HTTP 客户端
│   ├── Endpoint/          # 端点管理
│   ├── Metrics/           # 监控指标
│   └── Exception/         # 异常处理
├── Im/                    # 即时通讯
│   ├── V1/               # IM V1 API
│   └── V2/               # IM V2 API  
├── Sms/                  # 短信服务
├── Rtc/                  # 实时音视频
├── Vod/                  # 点播服务
├── Live/                 # 直播服务
├── Meeting/              # 会议服务
└── Neroom/               # 房间组件

🔧 高级用法

自定义端点配置

use YunxinServerSdk\Core\EndpointConfig;
use YunxinServerSdk\Core\Endpoint\FixedEndpointSelector;

$endpointConfig = new EndpointConfig();
$endpointConfig->setEndpointSelector(
    new FixedEndpointSelector('https://your-private-api.example.com')
);

$client = YunxinApiHttpClient::builderWithBizName(BizName::im(), $appkey, $appsecret)
    ->endpointConfig($endpointConfig)
    ->build();

自定义重试策略

use YunxinServerSdk\Core\Endpoint\RetryPolicy;
use YunxinServerSdk\Core\Endpoint\RetryAction;

class CustomRetryPolicy implements RetryPolicy 
{
    public function shouldRetry(int $httpCode, int $attempt): RetryAction 
    {
        if ($attempt >= 3) {
            return RetryAction::noRetry();
        }
        
        if ($httpCode >= 500) {
            return RetryAction::retry(1000 * $attempt); // 递增延迟重试
        }
        
        return RetryAction::noRetry();
    }
}

Metrics 监控集成

use YunxinServerSdk\Core\Metrics\MetricsConfig;

$metricsConfig = new MetricsConfig();
$metricsConfig->setEnabled(true);
$metricsConfig->setCallback(function($metrics) {
    // 自定义指标处理逻辑
    error_log("API Metrics: " . json_encode($metrics));
});

$client = YunxinApiHttpClient::builderWithBizName(BizName::im(), $appkey, $appsecret)
    ->metricsConfig($metricsConfig)
    ->build();

🔍 故障排查

启用调试模式

// 方法 1: 环境变量
putenv('YUNXIN_SDK_DEBUG=true');

// 方法 2: 配置日志
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('yunxin-sdk');
$logger->pushHandler(new StreamHandler('php://stdout', Logger::DEBUG));

$client = YunxinApiHttpClient::builderWithBizName(BizName::im(), $appkey, $appsecret)
    ->logger($logger)
    ->build();

常见问题

Q: 接口调用返回 403 错误 A: 检查 AppKey 和 AppSecret 是否正确，确认应用权限配置

Q: 网络超时错误 A: 调整超时设置或检查网络连接

$client = YunxinApiHttpClient::builderWithBizName(BizName::im(), $appkey, $appsecret)
    ->timeoutMillis(10000) // 10秒超时
    ->build();

Q: 如何查看详细的请求响应日志？ A: 启用 TraceId 和调试模式，查看日志输出

📈 性能与测试

测试覆盖率: 73 个测试用例，覆盖所有核心功能
代码质量: PSR-12 规范，PHPStan Level 7 静态分析
性能表现: 基于 Guzzle 的高性能 HTTP 客户端
内存使用: 优化的对象复用，减少内存占用

🤝 贡献指南

我们欢迎任何形式的贡献！

提交 Issue

详细描述问题场景和复现步骤
提供相关的错误日志和环境信息
说明期望的行为结果

提交 Pull Request

Fork 本仓库
创建特性分支: git checkout -b feature/amazing-feature
提交更改: git commit -m 'Add amazing feature'
推送分支: git push origin feature/amazing-feature
提交 Pull Request

开发规范

遵循 PSR-12 代码规范
添加相应的单元测试
更新相关文档
通过所有 CI 检查

📄 许可证

本项目基于 MIT 许可证开源 - 查看 LICENSE 文件了解详情。

🔗 相关链接

网易云信 PHP SDK
让云信集成更简单 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
docs		docs
examples		examples
src/YunxinServerSdk		src/YunxinServerSdk
tests		tests
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
phpunit.xml.dist		phpunit.xml.dist

License

netease-im/yunxin-server-sdk-php

Folders and files

Latest commit

History

Repository files navigation