# laravel-wecom

**Repository Path**: guolei19850528/laravel-wecom

## Basic Information

- **Project Name**: laravel-wecom
- **Description**: laravel-wecom
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-04
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Laravel 企业微信扩展包

一个功能强大的 Laravel 扩展包，提供企业微信 Webhook 和 Server API 的便捷操作。

## 功能特性

### Webhook API
- 支持发送文本消息（支持 @ 用户和 @ 手机号）
- 支持发送 Markdown 消息（包括 Markdown V2）
- 支持发送图片消息
- 支持发送图文消息
- 支持发送文件消息
- 支持发送语音消息

### Server API
- 支持获取和刷新访问令牌
- 支持上传媒体文件（file、voice、image、video）
- 支持上传临时图片
- 支持发送各种类型的消息（文本、图片、语音、视频、文件、文本卡片、图文、mpnews、Markdown等）
- 支持消息的重复检查和ID转译

## 安装

使用 Composer 安装扩展包：

```bash
composer require guolei19850528/laravel-wecom
```

## 配置

### Webhook API 配置

在使用 Webhook API 时，需要获取企业微信机器人的 Webhook 密钥。

### Server API 配置

在使用 Server API 时，需要获取以下信息：
- 企业 ID (corpid)
- 应用密钥 (corpsecret)
- 应用 ID (agentid)

## 使用示例

### Webhook API

#### 发送文本消息

```php
use Guolei19850528\Laravel\Wecom\Webhook\Message;

// 创建消息实例
$message = new Message('your-webhook-key');

// 格式化文本消息
$textMessage = $message->textFormatter(
    content: '这是一条测试消息',
    mentionedList: ['user1', 'user2'], // @指定用户
    mentionedMobileList: ['13800138000'] // @指定手机号
);

// 发送消息
$message->send($textMessage);
```

#### 发送 Markdown 消息

```php
// 格式化 Markdown 消息
$markdownMessage = $message->markdownFormatter(
    content: "# 标题\n**加粗文本**\n[链接](https://example.com)"
);

// 发送消息
$message->send($markdownMessage);
```

#### 上传文件并发送

```php
// 上传文件
$mediaId = $message->uploadMedia(
    attach: ['media', file_get_contents('path/to/file.pdf'), 'file.pdf']
);

// 格式化文件消息
$fileMessage = $message->fileFormatter($mediaId);

// 发送消息
$message->send($fileMessage);
```

### Server API

#### 初始化客户端

```php
use Guolei19850528\Laravel\Wecom\Server\Message;

// 创建消息实例
$message = new Message(
    corpid: 'your-corpid',
    corpsecret: 'your-corpsecret',
    agentid: 'your-agentid'
);

// 刷新访问令牌
$message->refreshAccessToken();
```

#### 发送文本消息

```php
// 格式化文本消息
$textMessage = $message->textFormatter(
    touser: '@all', // 发送给所有人
    content: '这是一条企业消息',
    safe: 0, // 安全级别，0表示普通消息
    enable_duplicate_check: 1 // 开启重复消息检查
);

// 发送消息
$message->send($textMessage);
```

#### 上传并发送图片

```php
// 上传图片
$mediaId = $message->mediaUpload(
    attach: ['media', file_get_contents('path/to/image.jpg'), 'image.jpg'],
    type: 'image'
);

// 格式化图片消息
$imageMessage = $message->imageFormatter(
    touser: '@all',
    mediaId: $mediaId
);

// 发送消息
$message->send($imageMessage);
```

#### 发送图文消息

```php
// 创建文章
$article = $message->newsArticleFormatter(
    title: '文章标题',
    description: '文章描述',
    url: 'https://example.com/article',
    picurl: 'https://example.com/image.jpg'
);

// 格式化图文消息
$newsMessage = $message->newsFormatter(
    touser: '@all',
    articles: ['articles' => [$article]]
);

// 发送消息
$message->send($newsMessage);
```

## API 文档

### Webhook API

#### Message 类

```php
// 构造函数
__construct(string $key = '', array $mentionedList = [], array $mentionedMobileList = [], string $baseUrl = 'https://qyapi.weixin.qq.com/')

// 发送消息
send(?array $data = null, string $url = '/cgi-bin/webhook/send?key={key}', ?array $urlParameters = null, ?array $options = null, ?\Closure $responseHandler = null, ?array $validatorRules = ['errcode' => 'required|integer|size:0'])

// 上传媒体文件
uploadMedia(?array $attach = null, ?array $data = null, ?string $url = '/cgi-bin/webhook/upload_media?key={key}&type={type}', ?string $type = 'file', ?array $urlParameters = null, ?array $options = null, ?\Closure $responseHandler = null, ?array $validatorRules = ['errcode' => 'required|integer|size:0'])
```

#### 消息格式化方法

- `textFormatter(string $content = '', array $mentionedList = [], array $mentionedMobileList = []): array`
- `markdownFormatter(string $content = ''): array`
- `markdownV2Formatter(string $content = ''): array`
- `imageFormatter(string $base64 = '', string $md5 = ''): array`
- `newsFormatter(array $articles = []): array`
- `newsArticleFormatter(string $title = '', string $description = '', string $url = '', string $picurl = ''): array`
- `fileFormatter(string $mediaId = ''): array`
- `voiceFormatter(string $mediaId = ''): array`

### Server API

#### Message 类

```php
// 构造函数
__construct(?string $corpid = null, ?string $corpsecret = null, string|int|null $agentid = null, ?string $baseUrl = 'https://qyapi.weixin.qq.com/')

// 获取访问令牌
accessToken(?array $query = [], ?string $url = '/cgi-bin/gettoken', ?array $urlParameters = null, ?array $options = [], ?\Closure $responseHandler = null, ?array $validatorRules = ['errcode' => 'required|integer|size:0'])

// 刷新访问令牌
refreshAccessToken(string $key = '', \DateTimeInterface|\DateInterval|int|null $ttl = 7100): static

// 上传媒体文件
mediaUpload(?array $attach = [], ?array $data = [], ?string $type = 'file', ?string $url = '/cgi-bin/media/upload?access_token={access_token}&type={type}', ?array $urlParameters = null, ?array $options = [], ?\Closure $responseHandler = null, ?array $validatorRules = ['errcode' => 'required|integer|size:0'])

// 上传临时图片
mediaUploadImg(?array $attach = [], ?array $data = [], ?string $url = '/cgi-bin/media/uploadimg?access_token={access_token}', ?array $urlParameters = null, ?array $options = [], ?\Closure $responseHandler = null, ?array $validatorRules = ['errcode' => 'required|integer|size:0'])

// 发送消息
send(?array $data = [], ?string $url = '/cgi-bin/message/send?access_token={access_token}', ?array $urlParameters = null, ?array $options = [], ?\Closure $responseHandler = null, ?array $validatorRules = ['errcode' => 'required|integer|size:0'])
```

#### 消息格式化方法

- `textFormatter(?string $touser = '', ?string $toparty = '', ?string $content = '', ?string $totag = '', string|int|null $agentid = null, ?int $safe = 0, ?int $enable_id_trans = 0, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`
- `imageFormatter(?string $touser = '', ?string $toparty = '', ?string $mediaId = '', ?string $totag = '', string|int|null $agentid = null, ?int $safe = 0, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`
- `voiceFormatter(?string $touser = '', ?string $toparty = '', ?string $mediaId = '', ?string $totag = '', string|int|null $agentid = null, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`
- `videoFormatter(?string $touser = '', ?string $toparty = '', ?string $mediaId = '', ?string $title = '', ?string $description = '', ?string $totag = '', string|int|null $agentid = null, ?int $safe = 0, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`
- `fileFormatter(?string $touser = '', ?string $toparty = '', ?string $mediaId = '', ?string $totag = '', string|int|null $agentid = null, ?int $safe = 0, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`
- `textcardFormatter(?string $touser = '', ?string $toparty = '', ?string $title = '', ?string $description = '', ?string $url = '', ?string $totag = '', string|int|null $agentid = null, ?int $enable_id_trans = 0, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`
- `newsFormatter(?string $touser = '', ?string $toparty = '', ?array $articles = [], ?string $totag = '', string|int|null $agentid = null, ?int $enable_id_trans = 0, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`
- `newsArticleFormatter(?string $title = '', ?string $description = '', ?string $url = '', ?string $picurl = '', ?string $appid = '', ?string $pagepath = ''): array`
- `mpnewsFormatter(?string $touser = '', ?string $toparty = '', ?array $articles = [], ?string $totag = '', string|int|null $agentid = null, ?int $safe = 0, ?int $enable_id_trans = 0, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`
- `mpnewsArticleFormatter(?string $title = '', ?string $thumb_media_id = '', ?string $url = '', ?string $author = '', ?string $content_source_url = '', ?string $content = '', ?string $digest = ''): array`
- `markdownFormatter(?string $touser = '', ?string $toparty = '', ?string $content = '', ?string $totag = '', string|int|null $agentid = null, ?int $enable_duplicate_check = 0, ?int $duplicate_check_interval = 1800): array`

## 注意事项

1. 确保在企业微信后台正确配置了 Webhook 密钥和 API 权限
2. 访问令牌的有效期为 7200 秒，Server API 会自动管理令牌的刷新和缓存
3. 发送消息时请注意频率限制，避免触发企业微信的限流机制
4. 上传的媒体文件有大小限制，具体请参考企业微信官方文档
5. Webhook API 和 Server API 的使用场景不同，请根据实际需求选择合适的 API

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个扩展包。