# goeasy-im

**Repository Path**: XiaoMingYu/goeasy-im

## Basic Information

- **Project Name**: goeasy-im
- **Description**: goeasy对应的IM服务端接口
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-15
- **Last Updated**: 2025-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GoEasy IM REST API PHP SDK

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

## 功能特性

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

### 群聊模块
- 订阅群聊
- 取消订阅群聊
- 获取群信息
- 获取群成员列表

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

### 消息撤回模块
- 撤回私聊消息
- 撤回群聊消息

## 安装

使用 Composer 安装：

```bash
composer require goeasy/php-sdk
```

## 基本使用

### 初始化

#### 基本初始化
```php
<?php

require 'vendor/autoload.php';

use GoEasy\GoEasy;

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

#### 从环境变量获取appkey
```php
<?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
<?php

require 'vendor/autoload.php';

use GoEasy\GoEasy;

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

#### 自定义API URL
```php
<?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
<?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 采用工厂类设计模式，通过以下方法获取各个功能模块：

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

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

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

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

## 模块使用指南

### 消息模块 (Message)

#### 发送私聊文本消息

```php
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();
}
```

#### 发送群聊文本消息

```php
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();
}
```

#### 发送自定义类型消息

```php
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 方法

```php
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)

#### 订阅群聊

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

#### 取消订阅群聊

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

#### 获取群信息

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

#### 获取群成员列表

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

### 历史消息模块 (History)

#### 查询私聊历史消息

```php
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();
}
```

#### 查询群聊历史消息

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

### 消息撤回模块 (Recall)

#### 撤回消息

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

## 消息格式

### 基本消息结构

```php
[
    '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 文档](https://docs.goeasy.io/2.x/im/rest-api/send-message)

## 支持

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