一个功能完整、设计优雅的 Coze AI 平台 PHP SDK，提供机器人管理、聊天对话、会话管理等核心功能。
- 🚀 高性能: 基于 Symfony HTTP Client，支持连接池和并发请求
- 🔐 安全认证: 完整的 JWT Bearer 认证机制，自动令牌刷新
- 💾 智能缓存: 多层缓存策略，提升性能和稳定性
- 📝 详细日志: 完整的日志记录系统，便于调试和监控
- 🛡️ 类型安全: 完整的 PHP 8.2+ 类型声明
- 🧪 测试覆盖: 全面的单元测试和集成测试
- 🔧 易于扩展: 模块化设计，易于扩展和维护
composer require pfinalclub/coze_sdk<?php
use CozeSdk\OfficialAccount\Application;
use CozeSdk\Kernel\Support\SimpleLogger;
// 创建应用实例
$app = new Application([
'kid' => 'your_kid_here',
'iss' => 'your_iss_here',
'keyPath' => '/path/to/your/private_key.pem',
'botId' => 'your_bot_id_here'
], new SimpleLogger());
// 验证配置
$app->validate();<?php
use CozeSdk\Chat\Chat;
// 创建聊天实例
$chat = new Chat($app);
// 发送消息
$response = $chat->setUserId('user_123')
->sendMessage('你好，请介绍一下PHP');
// 处理响应
foreach ($response['messages'] as $message) {
echo $message['content'] . "\n";
}<?php
use CozeSdk\Bot\Bot;
// 创建机器人管理实例
$bot = new Bot($app->getAccessToken());
// 获取机器人列表
$botList = $bot->setSpaceId('your_space_id')
->getBotList();
// 获取机器人详情
$botDetail = $bot->getBotDetail('bot_id_here');
// 搜索机器人
$searchResults = $bot->searchBots('关键词');SDK 提供了强大的流式传输支持，支持多种处理方式：
<?php
use CozeSdk\Chat\Chat;
$chat = new Chat($app);
// 创建流式聊天（兼容旧版本）
$streamCallback = $chat->setUserId('user_123')
->Query('请写一个PHP函数')
->Build(true);
// 执行流式响应
$streamCallback();<?php
use CozeSdk\Chat\Chat;
use CozeSdk\Kernel\Support\{
ConsoleStreamHandler,
JsonStreamHandler,
MemoryStreamHandler,
CallbackStreamHandler
};
$chat = new Chat($app);
// 1. 控制台输出流式处理器
$consoleHandler = new ConsoleStreamHandler();
$result = $chat->sendStreamMessage('你好，请介绍一下PHP', $consoleHandler);
// 2. JSON流式处理器
$jsonHandler = new JsonStreamHandler();
$result = $chat->sendStreamMessage('写一个简单的函数', $jsonHandler);
// 3. 内存流式处理器
$memoryHandler = new MemoryStreamHandler();
$result = $chat->sendStreamMessage('解释什么是OOP', $memoryHandler);
// 4. 回调流式处理器（最灵活）
$callbackHandler = new CallbackStreamHandler(
function($chunk, $metadata) {
// 处理每个数据块
echo $chunk;
flush();
return true; // 继续处理
},
function($metadata) {
// 流式传输开始
echo "开始接收数据...\n";
},
function($metadata) {
// 流式传输结束
echo "\n接收完成\n";
},
function($error, $metadata) {
// 错误处理
echo "错误: " . $error->getMessage() . "\n";
}
);
$result = $chat->sendStreamMessage('请写一个详细的教程', $callbackHandler);SDK 还提供了更高级的流式传输功能：
<?php
use CozeSdk\Chat\Chat;
use CozeSdk\Kernel\Support\{
EnhancedStreamHandler,
RealTimeTextHandler,
ProgressMonitorHandler
};
$chat = new Chat($app);
// 1. 实时文本流式传输
$result = $chat->sendRealTimeMessage('请介绍一下PHP');
echo "文本长度: " . strlen($result) . " 字符";
// 2. 带进度监控的流式传输
$result = $chat->sendProgressMessage('请写一个详细的教程', 20);
echo "统计信息: " . json_encode($result['stats']);
// 3. 增强流式处理器
$result = $chat->sendEnhancedMessage(
'请解释什么是OOP',
// 文本回调
function($text, $metadata) {
echo $text;
flush();
return true;
},
// 数据回调
function($data, $metadata) {
// 处理结构化数据
return true;
},
// 进度回调
function($stats, $metadata) {
echo "\r进度: {$stats['total_text_length']} 字符";
}
);SDK 提供了多种流式处理器：
- ConsoleStreamHandler: 控制台输出
- JsonStreamHandler: JSON数据解析
- MemoryStreamHandler: 内存存储
- FileStreamHandler: 文件存储
- CallbackStreamHandler: 回调处理
- RealTimeTextHandler: 实时文本显示
- ProgressMonitorHandler: 进度监控
- EnhancedStreamHandler: 增强处理能力
主要的应用配置和管理类。
$app = new Application($config, $logger, $cache, $httpClient);
// 获取访问令牌
$accessToken = $app->getAccessToken();
// 获取机器人ID
$botId = $app->getBotId();
// 验证配置
$app->validate();聊天对话功能。
$chat = new Chat($app, $httpClient, $cache, $logger);
// 设置参数
$chat->setBotId('bot_id')
->setUserId('user_id')
->setConversationId('conversation_id');
// 发送消息
$response = $chat->sendMessage('消息内容');
// 获取聊天详情
$detail = $chat->getChatRetrieve('chat_id');
// 获取消息列表
$messages = $chat->getChatMessageList('chat_id');机器人管理功能。
$bot = new Bot($accessToken, $httpClient, $cache, $logger);
// 设置空间ID
$bot->setSpaceId('space_id');
// 获取机器人列表
$botList = $bot->getBotList();
// 获取机器人详情
$botDetail = $bot->getBotDetail('bot_id');
// 获取机器人ID列表
$botIds = $bot->getBotIdList();
// 搜索机器人
$results = $bot->searchBots('关键词');
// 获取统计信息
$stats = $bot->getBotStats();| 配置项 | 类型 | 必需 | 描述 |
|---|---|---|---|
kid |
string | 是 | 密钥ID |
iss |
string | 是 | 发行者ID |
keyPath |
string | 是 | 私钥文件路径 |
botId |
string | 否 | 机器人ID |
iat |
string | 否 | 令牌签发时间（默认当前时间） |
exp |
string | 否 | 令牌过期时间（默认1小时后） |
token |
string | 否 | 预生成的令牌 |
# 运行单元测试（推荐，不依赖API）
composer test:unit
# 运行流式传输测试
composer test:stream
# 运行API测试（需要有效配置）
composer test:api
# 运行所有测试
composer test:all
# 生成测试覆盖率报告
composer test:coverage
# 生成测试报告
composer test:report# 运行单元测试
php tests/run_tests.php --unit
# 运行流式传输测试
php tests/run_tests.php --stream
# 运行所有测试
php tests/run_tests.php --all
# 显示帮助信息
php tests/run_tests.php --help# 运行简单单元测试
php tests/simple_unit_test.php
# 运行快速功能测试
php tests/quick_test.php
# 验证PHPUnit配置
php tests/test_phpunit.php- 模拟模式（默认）: 不需要真实API配置，适合开发和CI
- 真实API模式: 需要有效的API配置，用于集成测试
详细测试说明请参考 测试指南
SDK 提供了完整的日志记录功能：
use CozeSdk\Kernel\Support\SimpleLogger;
// 创建日志实例
$logger = new SimpleLogger(true); // 启用日志
// 日志文件位置
// Linux/Mac: /tmp/coze_sdk_logs/coze_sdk.log
// Windows: C:\Users\{username}\AppData\Local\Temp\coze_sdk_logs\coze_sdk.logSDK 支持多种缓存策略：
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
// 文件系统缓存
$cache = new Psr16Cache(new FilesystemAdapter('coze', 1500));
// Redis 缓存（需要安装 redis 扩展）
$cache = new Psr16Cache(new RedisAdapter($redis));
// 内存缓存（测试用）
$cache = new Psr16Cache(new ArrayAdapter());SDK 提供了详细的错误处理：
use CozeSdk\Kernel\Exception\HttpException;
use CozeSdk\Kernel\Exception\ParamsException;
try {
$response = $chat->sendMessage('消息');
} catch (ParamsException $e) {
// 参数错误
echo "参数错误: " . $e->getMessage();
} catch (HttpException $e) {
// HTTP 请求错误
echo "请求错误: " . $e->getMessage();
} catch (\Exception $e) {
// 其他错误
echo "未知错误: " . $e->getMessage();
}欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 打开 Pull Request
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
PFinal南丞 - GitHub - lampxiezi@163.com
感谢 Coze AI 平台提供的优秀 API 服务。
⭐ 如果这个项目对你有帮助，请给它一个星标！