README

这是 GoEasy IM REST API 的 PHP SDK，采用工厂类设计模式，提供了完整的即时通讯功能，包括发送消息、订阅群聊、查询历史消息和撤回消息等。

功能特性

消息模块

支持发送文本消息和自定义消息
支持私聊和群聊
支持通知栏提醒
支持发送者和接收者信息设置

群聊模块

订阅群聊
取消订阅群聊
获取群信息
获取群成员列表

历史消息模块

查询私聊历史消息
查询群聊历史消息
支持分页查询
支持按时间范围查询

消息撤回模块

撤回私聊消息
撤回群聊消息

安装

使用 Composer 安装：

composer require goeasy/php-sdk

基本使用

初始化

基本初始化

<?php

require 'vendor/autoload.php';

use GoEasy\GoEasy;

// 初始化 GoEasy 客户端（工厂类）
// 默认使用杭州服务器
$goEasy = new GoEasy('your-appkey');

从环境变量获取appkey

<?php

require 'vendor/autoload.php';

use GoEasy\GoEasy;

// 确保已设置环境变量 GOEASY_APPKEY
putenv('GOEASY_APPKEY=your-appkey');

// 从环境变量自动获取appkey
$goEasy = new GoEasy();

// 或者指定自定义环境变量名称
$goEasy = new GoEasy(null, [
    'envKey' => 'CUSTOM_GOEASY_APPKEY'
]);

选择服务器位置

<?php

require 'vendor/autoload.php';

use GoEasy\GoEasy;

// 使用新加坡服务器
$goEasy = new GoEasy('your-appkey', [
    'serverLocation' => 'singapore'
]);

自定义API URL

<?php

require 'vendor/autoload.php';

use GoEasy\GoEasy;

// 使用自定义API URL（支持后续扩展）
$goEasy = new GoEasy('your-appkey', [
    'customUrl' => 'https://custom-api.goeasy.io/v2/im'
]);

SSL证书配置

<?php

require 'vendor/autoload.php';

use GoEasy\GoEasy;

// 禁用SSL证书验证（仅开发环境使用）
$goEasy = new GoEasy('your-appkey', [
    'verifySSL' => false
]);

// 或指定CA证书文件路径
// $goEasy = new GoEasy('your-appkey', [
//     'caCertificate' => '/path/to/ca-cert.pem'
// ]);

获取功能模块

GoEasy 采用工厂类设计模式，通过以下方法获取各个功能模块：

// 获取消息模块
$messageModule = $goEasy->message();

// 获取群聊模块
$groupModule = $goEasy->group();

// 获取历史消息模块
$historyModule = $goEasy->history();

// 获取消息撤回模块
$recallModule = $goEasy->recall();

模块使用指南

消息模块 (Message)

发送私聊文本消息

try {
    $result = $goEasy->message()->sendPrivateText(
        'senderId',           // 发送者 ID
        'receiverId',         // 接收者 ID
        'Hello, GoEasy!',     // 消息内容
        [                     // 发送者附加信息（可选）
            'avatar' => '/www/avatar.png',
            'nickname' => 'Neo'
        ],
        [                     // 接收者附加信息（可选）
            'avatar' => '/images/receiver.png',
            'name' => 'Wallace'
        ],
        [                     // 通知栏设置（可选）
            'title' => '新消息',
            'body' => '你有一条新消息'
        ]
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '发送失败: ' . $e->getMessage();
}

发送群聊文本消息

try {
    $result = $goEasy->message()->sendGroupText(
        'senderId',           // 发送者 ID
        'groupId',            // 群组 ID
        'Hello, Group!',      // 消息内容
        [                     // 发送者附加信息（可选）
            'avatar' => '/www/avatar.png',
            'nickname' => 'Neo'
        ],
        [                     // 群组附加信息（可选）
            'avatar' => '/images/group.png',
            'name' => '技术交流群'
        ],
        [                     // 通知栏设置（可选）
            'title' => '群消息',
            'body' => '你有一条新的群消息'
        ]
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '发送失败: ' . $e->getMessage();
}

发送自定义类型消息

try {
    // 发送私聊自定义消息
    $result = $goEasy->message()->sendPrivateMessage(
        'senderId',
        'receiverId',
        'order',              // 自定义消息类型
        [                     // 自定义消息内容
            'number' => '20201818005',
            'product' => 'Mate 30 Pro',
            'image' => 'https://example.com/product.jpg',
            'price' => 3999
        ],
        ['avatar' => '/www/avatar.png', 'nickname' => 'Neo'],
        ['avatar' => '/images/receiver.png', 'name' => 'Wallace'],
        ['title' => '新订单', 'body' => '你有一个新的订单通知']
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '发送失败: ' . $e->getMessage();
}

// 发送群聊自定义消息
$result = $goEasy->message()->sendGroupMessage(
    'senderId',
    'groupId',
    'system',
    ['type' => 'announcement', 'content' => '系统维护通知'],
    ['nickname' => '系统管理员'],
    ['name' => '技术交流群'],
    ['title' => '系统通知', 'body' => '您有一条新的系统通知']
);

使用通用 sendMessage 方法

try {
    $result = $goEasy->message()->send([
        'senderId' => 'user002',
        'senderData' => [
            'avatar' => '/www/avatar.png',
            'nickname' => 'Neo'
        ],
        'to' => [
            'type' => 'private',  // private 或 group
            'id' => 'userId',      // 用户 ID 或群组 ID
            'data' => [
                'avatar' => '/images/Avatar-2.png',
                'name' => 'Wallace'
            ]
        ],
        'type' => 'text',        // 消息类型或自定义类型
        'payload' => 'Hello, GoEasy!',  // 消息内容
        'notification' => [      // 通知栏设置（可选）
            'title' => 'hello world',
            'body' => '你有一条新消息'
        ]
    ]);
    
    print_r($result);
} catch (Exception $e) {
    echo '发送失败: ' . $e->getMessage();
}

群聊模块 (Group)

订阅群聊

try {
    $result = $goEasy->group()->subscribe(
        'userId',           // 用户 ID
        'groupId',          // 群组 ID
        [                   // 附加信息（可选）
            'nickname' => 'Neo',
            'avatar' => '/www/avatar.png'
        ]
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '订阅失败: ' . $e->getMessage();
}

取消订阅群聊

try {
    $result = $goEasy->group()->unsubscribe(
        'userId',           // 用户 ID
        'groupId'           // 群组 ID
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '取消订阅失败: ' . $e->getMessage();
}

获取群信息

try {
    $result = $goEasy->group()->getInfo(
        'groupId'           // 群组 ID
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '获取群信息失败: ' . $e->getMessage();
}

获取群成员列表

try {
    $result = $goEasy->group()->getMembers(
        'groupId',          // 群组 ID
        1,                  // 页码（可选，默认1）
        20                  // 每页数量（可选，默认20）
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '获取群成员失败: ' . $e->getMessage();
}

历史消息模块 (History)

查询私聊历史消息

try {
    $result = $goEasy->history()->getPrivateHistory(
        'userId1',          // 用户1 ID
        'userId2',          // 用户2 ID
        1,                  // 页码（可选，默认1）
        20,                 // 每页数量（可选，默认20）
        1609459200000,      // 开始时间戳（可选）
        1612137600000       // 结束时间戳（可选）
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '查询失败: ' . $e->getMessage();
}

查询群聊历史消息

try {
    $result = $goEasy->history()->getGroupHistory(
        'groupId',          // 群组 ID
        1,                  // 页码（可选，默认1）
        20,                 // 每页数量（可选，默认20）
        1609459200000,      // 开始时间戳（可选）
        1612137600000       // 结束时间戳（可选）
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '查询失败: ' . $e->getMessage();
}

消息撤回模块 (Recall)

撤回消息

try {
    $result = $goEasy->recall()->recallMessage(
        'messageId',        // 消息 ID
        'senderId'          // 发送者 ID
    );
    
    print_r($result);
} catch (Exception $e) {
    echo '撤回失败: ' . $e->getMessage();
}

消息格式

基本消息结构

[
    'senderId' => '发送者ID',
    'senderData' => [        // 可选
        'avatar' => '头像URL',
        'nickname' => '昵称'
    ],
    'to' => [
        'type' => 'private|group',
        'id' => '接收者ID|群组ID',
        'data' => [           // 可选
            'avatar' => '头像URL',
            'name' => '名称'
        ]
    ],
    'type' => 'text|自定义类型',
    'payload' => '消息内容',
    'notification' => [       // 可选
        'title' => '通知标题',
        'body' => '通知内容'
    ]
]

错误处理

SDK 会抛出以下类型的异常：

InvalidArgumentException：参数错误
GuzzleHttp\Exception\GuzzleException：HTTP 请求错误

建议使用 try-catch 块捕获异常。

注意事项

确保使用正确的 appkey
消息类型支持文本消息和自定义消息
暂不支持服务端直接发送图片、语音、视频和文件，但可以用自定义消息包含路径的方式实现
所有方法都可能抛出异常，请使用 try-catch 块进行错误处理
历史消息查询默认每页返回 20 条记录
消息撤回功能有时间限制，请参考 GoEasy 官方文档

文档

详细 API 文档请参考：GoEasy REST API 文档

支持

如果您有任何问题或建议，请联系：support@goeasy.io

goeasy / php-sdk

Maintainers

Details