README

Laravel 多驱动即时通信 SDK，统一封装腾讯云 IM、融云、环信、阿里云互动消息、华为云 IM，以及自定义后端。

环境要求

PHP ^8.3
Laravel / Illuminate ^12.0 | ^13.0
扩展：ext-json、ext-zlib
Guzzle ^7.8

安装

composer require caiyun/im

Laravel 会自动注册服务提供者与 Facade。如需发布配置：

php artisan vendor:publish --tag=im-config

配置

在 .env 中指定默认驱动：

IM_DRIVER=tencent

可选队列配置（预留）：

IM_QUEUE_CONNECTION=database
IM_QUEUE=im

腾讯云 IM（默认）

IM_TENCENT_END_POINT=https://console.tim.qq.com
IM_TENCENT_SDK_APP_ID=1400000000
IM_TENCENT_SECRET_KEY=your-secret-key
IM_TENCENT_ADMINISTRATOR=administrator
IM_TENCENT_USER_SIG_TTL=5184000
IM_TENCENT_ADMIN_SIG_TTL=86400

融云

IM_RONGCLOUD_END_POINT=https://api.rong-api.com
IM_RONGCLOUD_APP_KEY=
IM_RONGCLOUD_APP_SECRET=

环信

IM_EASEMOB_END_POINT=https://a1.easemob.com
IM_EASEMOB_ORG_NAME=
IM_EASEMOB_APP_NAME=
IM_EASEMOB_CLIENT_ID=
IM_EASEMOB_CLIENT_SECRET=

阿里云互动消息

IM_ALIYUN_END_POINT=https://live-im.cn-shanghai.aliyuncs.com
IM_ALIYUN_ACCESS_KEY_ID=
IM_ALIYUN_ACCESS_KEY_SECRET=
IM_ALIYUN_APP_ID=
IM_ALIYUN_APP_SIGN=
IM_ALIYUN_REGION_ID=cn-shanghai

华为云 IM

IM_HUAWEI_END_POINT=https://im-api.cloud.huawei.com.cn
IM_HUAWEI_APP_ID=
IM_HUAWEI_APP_SECRET=
IM_HUAWEI_TOKEN_END_POINT=https://oauth-login.cloud.huawei.com.cn/oauth2/v3/token

自定义后端

IM_CUSTOM_END_POINT=https://im.example.com
IM_CUSTOM_APP_KEY=
IM_CUSTOM_APP_SECRET=
IM_CUSTOM_APP_CODE=

完整配置见 config/im.php。

快速使用

Facade

use Caiyun\Im\Facades\Im;
use Caiyun\Im\Api\Tencent\Message as TencentMessage;

// 导入 / 更新用户
Im::user()->createOrUpdateUser([
    'external_user_id' => 'user_1',
    'nickname' => '张三',
    'avatar' => 'https://example.com/avatar.png',
]);

// 获取客户端登录凭证
$token = Im::user()->getImToken('user_1');

// 发送单聊文本（腾讯云示例）
Im::message()->send(
    'user_1',
    'user_2',
    [TencentMessage::text('你好')],
);

// 创建会话 / 群组
Im::conversation()->store([
    'type' => 'group',
    'subject' => '项目群',
    'owner_user_id' => 'user_1',
    'member_user_ids' => ['user_1', 'user_2'],
]);

切换驱动

use Caiyun\Im\Facades\Im;

Im::driver('rongcloud')->api('user')->getImToken('user_1');
Im::driver('easemob')->api('message')->send(...);

容器解析

use Caiyun\Im\Im;

$im = app(Im::class);
$im->api('user')->getImToken('user_1');

统一 API 契约

各驱动尽量实现同一套接口，便于业务层无感切换：

API	方法
`user`	`createOrUpdateUser`、`getUser`、`updateUser`、`getImToken`
`conversation`	`store`、`getMessages`、`getMembers`、`postMessage`
`message`	`send`

custom 驱动目前提供 user、conversation，不含 message。

各驱动还可暴露厂商原生能力（如腾讯云的 import、batchSend、createGroup 等），可直接调用对应 API 类方法。

支持的驱动

驱动名	说明
`tencent`	腾讯云即时通信 IM
`rongcloud`	融云
`easemob`	环信
`aliyun`	阿里云互动消息
`huawei`	华为云 IM
`custom`	自建 IM 后端

腾讯云常用示例

use Caiyun\Im\Facades\Im;
use Caiyun\Im\Api\Tencent\Message as TencentMessage;

$user = Im::driver('tencent')->api('user');

$user->import('user_1', '张三', 'https://example.com/a.png');
$user->setProfile('user_1', [
    'Tag_Profile_IM_Nick' => '张三',
]);
$sig = $user->getImToken('user_1', 86400);

Im::message()->send('user_1', 'user_2', [
    TencentMessage::text('hello'),
]);

Im::message()->batchSend('user_1', ['user_2', 'user_3'], [
    TencentMessage::custom(json_encode(['type' => 'notice'])),
]);

Im::conversation()->createGroup('Public', '公告群', [
    'Owner_Account' => 'user_1',
    'MemberList' => [
        ['Member_Account' => 'user_1'],
        ['Member_Account' => 'user_2'],
    ],
]);

消息元素辅助方法：

TencentMessage::text($text)
TencentMessage::custom($data, $description = '', $extension = '', $sound = '')
TencentMessage::image($url, $uuid, $size, $width, $height)
TencentMessage::sound($url, $uuid, $size, $seconds)

异常

异常类	场景
`Caiyun\Im\Exceptions\ImException`	通用 IM 业务 / 响应错误
`Caiyun\Im\Exceptions\UnsupportedDriverException`	未知驱动名
`Caiyun\Im\Exceptions\InvalidConfigurationException`	驱动配置缺失

开发与测试

composer install
composer test
composer lint
composer check   # lint:check + test

License

proprietary

caiyun / im

Maintainers

Package info

Statistics

Security