mirror of
https://github.com/crmeb/CRMEB.git
synced 2026-11-18 07:50:34 +00:00
206 lines
6.3 KiB
Markdown
206 lines
6.3 KiB
Markdown
# 邮件驱动扩展开发指南
|
||
|
||
## 概述
|
||
|
||
邮件驱动扩展位于 `driver/email/{Driver}/` 目录,负责对接各类邮件发送服务(SMTP、阿里云邮件推送、QQ邮箱等)。
|
||
|
||
系统通过 `crmeb\services\driver\DriverRegistry` 扫描各驱动包的 `plugin.json` 完成驱动注册。**邮件驱动状态互斥**,同时只能启用一个驱动。
|
||
|
||
## 已有驱动
|
||
|
||
| 驱动目录 | 驱动标识 | 说明 |
|
||
|---------|---------|------|
|
||
| [Smtp](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/email/Smtp/) | `smtp` | SMTP 通用邮件(标准 SMTP 协议) |
|
||
| [AliyunDm](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/email/AliyunDm/) | `aliyun_dm` | 阿里云邮件推送(DirectMail API) |
|
||
| [Qq](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/email/Qq/) | `qq` | QQ邮箱(SMTP 方式) |
|
||
|
||
## 开发步骤
|
||
|
||
### 1. 创建驱动目录
|
||
|
||
```bash
|
||
mkdir -p driver/email/{DriverName}
|
||
```
|
||
|
||
### 2. 创建 plugin.json
|
||
|
||
```json
|
||
{
|
||
"key": "your_driver_key",
|
||
"name": "邮件驱动名称",
|
||
"description": "驱动功能简述",
|
||
"version": "1.0.0",
|
||
"author": "CRMEB",
|
||
"type": "driver",
|
||
"path": "driver/email/YourDriver",
|
||
"require": {
|
||
"crmeb": "^6.0",
|
||
"php": "^8.0"
|
||
},
|
||
"driver": {
|
||
"name": "邮件驱动名称",
|
||
"driver_key": "your_driver_key",
|
||
"icon": "icon-xxx",
|
||
"is_builtin": true,
|
||
"sort": 100,
|
||
"capabilities": ["send"],
|
||
"config_fields": [
|
||
{"field": "host", "label": "SMTP服务器", "type": "text", "required": true, "group": "服务器"},
|
||
{"field": "port", "label": "SMTP端口", "type": "text", "group": "服务器", "default": "465"},
|
||
{"field": "username", "label": "邮箱地址", "type": "text", "required": true, "group": "账号"},
|
||
{"field": "password", "label": "密码/授权码", "type": "password", "required": true, "group": "账号"},
|
||
{"field": "from_name", "label": "发件人名称", "type": "text", "group": "账号", "default": "CRMEB"}
|
||
],
|
||
"help_doc": {
|
||
"title": "使用说明",
|
||
"steps": ["步骤1", "步骤2"],
|
||
"link": "https://example.com"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### plugin.json driver 子对象字段说明
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | string | ✅ | 驱动名称 |
|
||
| `driver_key` | string | ✅ | 驱动唯一标识 |
|
||
| `icon` | string | ❌ | 图标类名 |
|
||
| `is_builtin` | bool | ❌ | 是否内置 |
|
||
| `sort` | int | ❌ | 排序 |
|
||
| `capabilities` | array | ❌ | 能力声明 |
|
||
| `config_fields` | array | ❌ | 配置字段 |
|
||
| `help_doc` | object | ❌ | 帮助文档 |
|
||
|
||
> 顶层字段(`key`/`name`/`description`/`version`/`author`/`type`/`path`/`require`)与通用 driver 插件一致,参见 [sms/DEVELOPMENT.md](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/sms/DEVELOPMENT.md) 的字段说明表。
|
||
|
||
### 3. 创建 Driver.php
|
||
|
||
```php
|
||
<?php
|
||
declare(strict_types=1);
|
||
|
||
namespace driver\email\{DriverName};
|
||
|
||
use crmeb\services\email\BaseEmail;
|
||
use crmeb\services\email\EmailInterface;
|
||
|
||
/**
|
||
* {DriverName} 邮件驱动
|
||
*/
|
||
class Driver extends BaseEmail implements EmailInterface
|
||
{
|
||
protected array $config = [];
|
||
|
||
/**
|
||
* 初始化配置
|
||
*/
|
||
protected function initialize(array $config): void
|
||
{
|
||
$this->config = $config;
|
||
}
|
||
|
||
/**
|
||
* 发送邮件
|
||
* @param string $to 收件人
|
||
* @param string $subject 主题
|
||
* @param string $content 内容(HTML格式)
|
||
* @param array $options 附加选项
|
||
* @return bool
|
||
*/
|
||
public function send(string $to, string $subject, string $content, array $options = []): bool
|
||
{
|
||
// 实现邮件发送逻辑
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 验证驱动
|
||
|
||
```php
|
||
use crmeb\services\driver\DriverRegistry;
|
||
|
||
$drivers = DriverRegistry::scan('email'); // 全部邮件驱动
|
||
$class = DriverRegistry::getDriverClass('email', 'your_driver_key'); // 完整类名 driver\email\YourDriver\Driver
|
||
```
|
||
|
||
## 接口规范
|
||
|
||
### 必须实现的方法
|
||
|
||
| 方法 | 说明 | 参数 | 返回值 |
|
||
|------|------|------|--------|
|
||
| `send()` | 发送邮件 | `$to`, `$subject`, `$content`, `$options` | `bool` |
|
||
|
||
### 传递多个收件人
|
||
|
||
```php
|
||
// 批量发送时循环调用 send(),或在单次调用中实现批量
|
||
$emails = ['a@example.com', 'b@example.com'];
|
||
foreach ($emails as $email) {
|
||
$driver->send($email, '主题', '内容');
|
||
}
|
||
```
|
||
|
||
## 配置存储
|
||
|
||
邮件驱动配置存储在 `eb_email_driver` 表的 `config_fields` JSON 字段中,**禁止写入 `system_config` 表**。
|
||
|
||
## 最佳实践
|
||
|
||
### 阿里云邮件推送(API 方式)
|
||
|
||
阿里云邮件推送通过 HTTP API 调用,需要实现签名算法:
|
||
|
||
```php
|
||
public function send(string $to, string $subject, string $content, array $options = []): bool
|
||
{
|
||
// 1. 构建请求参数
|
||
$params = [
|
||
'Action' => 'SingleSendMail',
|
||
'AccessKeyId' => $this->config['access_key_id'],
|
||
// ...
|
||
];
|
||
// 2. 生成签名
|
||
$params['Signature'] = $this->generateSignature($params, $secret);
|
||
// 3. 发送 HTTP 请求
|
||
$response = Http::get($url . '?' . http_build_query($params));
|
||
// 4. 处理响应
|
||
}
|
||
```
|
||
|
||
### SMTP 方式
|
||
|
||
SMTP 方式推荐使用第三方库(如 PHPMailer、Symfony Mailer)实现,配置字段通常包含:
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `host` | SMTP 服务器地址 |
|
||
| `port` | SMTP 端口(465/SSL,587/TLS) |
|
||
| `username` | 邮箱账号 |
|
||
| `password` | 密码或授权码 |
|
||
| `from_name` | 发件人显示名称 |
|
||
|
||
### 错误处理
|
||
|
||
```php
|
||
public function send(...): bool
|
||
{
|
||
if (empty($to)) {
|
||
return $this->setError('收件人不能为空');
|
||
}
|
||
try {
|
||
// 发送逻辑
|
||
} catch (\Throwable $e) {
|
||
return $this->setError('邮件发送异常: ' . $e->getMessage());
|
||
}
|
||
}
|
||
```
|
||
|
||
## 参考实现
|
||
|
||
- [阿里云邮件推送](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/email/AliyunDm/) — HTTP API 方式实现
|
||
- [QQ邮箱](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/email/Qq/) — SMTP 方式实现
|
||
- [SMTP通用](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/email/Smtp/) — 通用 SMTP 实现
|