邮件开发指南

概述

DSMall Pro 邮件系统基于 PHPMailer 构建，提供完整的邮件发送功能，支持SMTP协议、HTML邮件、附件发送等功能。系统已集成邮件发送工具类，并支持通过系统通知模板进行邮件发送。

环境要求

1. 依赖安装

系统使用以下Composer包：

bash

# 安装PHPMailer邮件发送库
composer require phpmailer/phpmailer:^6.9

2. 系统要求

PHP >= 8.0
ThinkPHP 8.0+
Composer 2.0+
SMTP服务器配置

3. 官方文档

邮件架构

1. 架构图

应用层 → Email工具类 → PHPMailer → SMTP服务器 → 邮件服务商
  ↓         ↓           ↓           ↓            ↓
业务逻辑  Email.php   PHPMailer   SMTP协议    腾讯/阿里/网易

2. 核心组件

Email: 邮件发送工具类 (app\deshang\utils\Email)
SysNoticeListener: 系统通知监听器，支持邮件发送
SysNoticeTpl: 系统通知模板管理
PHPMailer: 底层邮件发送库
SMTP: 邮件传输协议

邮件工具类

1. Email类结构

php

<?php

namespace app\deshang\utils;

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

class Email
{
    protected $mailer;
    protected $config = [
        'smtp_host' => '',      // SMTP服务器地址
        'smtp_port' => 465,     // SMTP服务器端口
        'smtp_user' => '',      // SMTP用户名
        'smtp_pass' => '',      // SMTP密码
        'smtp_secure' => 'ssl', // 安全协议(ssl/tls)
        'smtp_debug' => 0,      // 调试级别(0-4)
        'charset' => 'utf-8',   // 字符集
        'smtp_from_email' => '',     // 发件人邮箱
        'smtp_from_name' => '',      // 发件人姓名
    ];
}

2. 核心功能

方法	说明	参数
`__construct()`	构造函数，初始化邮件配置	`array $config`
`setFrom()`	设置发件人	`string $email, string $name`
`addAddress()`	添加收件人	`string $email, string $name`
`addCC()`	添加抄送	`string $email, string $name`
`addBCC()`	添加密送	`string $email, string $name`
`addAttachment()`	添加附件	`string $path, string $name`
`clearAll()`	清除所有收件人和附件	无
`send()`	发送邮件	`string $subject, string $body, string $altBody`

系统集成使用

1. 系统通知邮件发送

系统已集成邮件发送功能，通过 SysNoticeListener 监听器实现：

php

// 触发系统通知邮件发送
event('SysNoticeListener', [
    'key' => 'user_welcome',  // 通知模板key
    'template_params' => [
        'username' => '张三',
        'email' => 'user@example.com',
        'mobile' => '13800138000',
        'code' => '123456'
    ],
    'receiver_params' => [
        'user_id' => 1
    ]
]);

2. 系统配置

邮件功能通过系统配置控制：

php

// 检查邮件是否启用
$email_is_enabled = sysConfig('email:email_is_enabled');

// 获取邮件配置
$email_config = sysConfig('email:email_config');

3. 通知模板配置

系统支持通过 sys_notice_tpl 表配置邮件模板：

email_switch: 邮件开关 (1=开启, 0=关闭)
email_template: 邮件模板内容
supported_channels: 支持的通知渠道 (包含 'email')

基础使用

1. 直接使用Email类

php

use app\deshang\utils\Email;

// 创建邮件对象
$email = new Email([
    'smtp_host' => 'smtp.example.com',
    'smtp_port' => 465,
    'smtp_user' => 'user@example.com',
    'smtp_pass' => 'password',
    'smtp_from_email' => 'sender@example.com',
    'smtp_from_name' => '发件人'
]);

2. 发送简单邮件

php

try {
    // 创建邮件对象
    $email = new Email([
        'smtp_host' => 'smtp.example.com',
        'smtp_port' => 465,
        'smtp_user' => 'user@example.com',
        'smtp_pass' => 'password',
        'smtp_from_email' => 'sender@example.com',
        'smtp_from_name' => '发件人'
    ]);
    
    // 添加收件人
    $email->addAddress('recipient@example.com', '收件人');
    
    // 发送邮件
    $email->send('邮件主题', '<p>这是HTML格式的邮件内容</p>');
    
    echo '邮件发送成功';
} catch (\Exception $e) {
    echo '邮件发送失败: ' . $e->getMessage();
}

业务场景应用

1. 用户注册欢迎邮件

php

// 在用户注册成功后发送欢迎邮件
public function sendWelcomeEmail($user_id, $user_email, $username)
{
    event('SysNoticeListener', [
        'key' => 'user_welcome',
        'template_params' => [
            'username' => $username,
            'email' => $user_email,
            'register_time' => date('Y-m-d H:i:s')
        ],
        'receiver_params' => [
            'user_id' => $user_id
        ]
    ]);
}

2. 密码重置邮件

php

// 发送密码重置邮件
public function sendPasswordResetEmail($user_id, $user_email, $reset_code)
{
    event('SysNoticeListener', [
        'key' => 'password_reset',
        'template_params' => [
            'email' => $user_email,
            'code' => $reset_code,
            'expire_time' => date('Y-m-d H:i:s', time() + 3600) // 1小时后过期
        ],
        'receiver_params' => [
            'user_id' => $user_id
        ]
    ]);
}

3. 订单状态通知邮件

php

// 订单支付成功通知
public function sendOrderPaidEmail($user_id, $order_info)
{
    event('SysNoticeListener', [
        'key' => 'order_paid',
        'template_params' => [
            'order_sn' => $order_info['order_sn'],
            'order_amount' => $order_info['order_amount'],
            'pay_time' => date('Y-m-d H:i:s')
        ],
        'receiver_params' => [
            'user_id' => $user_id
        ]
    ]);
}

配置说明

1. 系统邮件配置

系统通过 sys_config 表管理邮件配置：

sql

-- 邮件功能开关
INSERT INTO `ds_sys_config` (`config_key`, `config_value`, `config_type`, `description`) 
VALUES ('email_is_enabled', '1', 'email', '邮件功能是否启用');

-- 邮件SMTP配置
INSERT INTO `ds_sys_config` (`config_key`, `config_value`, `config_type`, `description`) 
VALUES ('email_config', '{"smtp_host":"smtp.qq.com","smtp_port":465,"smtp_user":"user@qq.com","smtp_pass":"auth_code","smtp_secure":"ssl","smtp_from_email":"user@qq.com","smtp_from_name":"系统通知"}', 'email', '邮件SMTP配置');

2. SMTP配置参数

配置项	说明	示例值
smtp_host	SMTP服务器地址	smtp.qq.com
smtp_port	SMTP服务器端口	465 (SSL) / 587 (TLS)
smtp_user	SMTP用户名	user@example.com
smtp_pass	SMTP密码	邮箱密码或授权码
smtp_secure	安全协议	ssl / tls
smtp_from_email	发件人邮箱	noreply@example.com
smtp_from_name	发件人名称	系统通知

3. 常用邮件服务商配置

3.1 QQ邮箱

json

{
    "smtp_host": "smtp.qq.com",
    "smtp_port": 465,
    "smtp_user": "your-qq@qq.com",
    "smtp_pass": "your-auth-code",
    "smtp_secure": "ssl",
    "smtp_from_email": "your-qq@qq.com",
    "smtp_from_name": "系统通知"
}

3.2 163邮箱

json

{
    "smtp_host": "smtp.163.com",
    "smtp_port": 465,
    "smtp_user": "your-email@163.com",
    "smtp_pass": "your-auth-code",
    "smtp_secure": "ssl",
    "smtp_from_email": "your-email@163.com",
    "smtp_from_name": "系统通知"
}

3.3 腾讯企业邮箱

json

{
    "smtp_host": "smtp.exmail.qq.com",
    "smtp_port": 465,
    "smtp_user": "your-email@company.com",
    "smtp_pass": "your-password",
    "smtp_secure": "ssl",
    "smtp_from_email": "your-email@company.com",
    "smtp_from_name": "公司名称"
}

3.4 Gmail

json

{
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_user": "your-email@gmail.com",
    "smtp_pass": "your-app-password",
    "smtp_secure": "tls",
    "smtp_from_email": "your-email@gmail.com",
    "smtp_from_name": "System Notification"
}

错误处理

1. 常见错误码

错误类型	说明	解决方案
SMTP连接失败	无法连接到SMTP服务器	检查网络连接和SMTP配置
认证失败	SMTP用户名或密码错误	检查用户名密码或授权码
收件人无效	收件人邮箱地址格式错误	检查邮箱地址格式
附件不存在	附件文件路径错误	检查文件路径和权限
邮件内容为空	邮件主题或内容为空	检查邮件内容

2. 异常处理

php

try {
    // 使用系统通知发送邮件
    event('SysNoticeListener', [
        'key' => 'test_email',
        'template_params' => [
            'username' => '测试用户',
            'content' => '测试内容'
        ],
        'receiver_params' => [
            'user_id' => 1
        ]
    ]);
    
    echo '邮件发送成功';
} catch (\Exception $e) {
    // 记录错误日志
    error_log("邮件发送失败: " . $e->getMessage());
    
    // 根据错误类型进行不同处理
    if (strpos($e->getMessage(), 'SMTP') !== false) {
        echo 'SMTP服务器连接失败，请检查网络配置';
    } elseif (strpos($e->getMessage(), 'authentication') !== false) {
        echo '邮箱认证失败，请检查用户名和密码';
    } else {
        echo '邮件发送失败: ' . $e->getMessage();
    }
}

3. 调试模式

php

// 开启调试模式
$email = new Email([
    'smtp_host' => 'smtp.example.com',
    'smtp_port' => 465,
    'smtp_user' => 'user@example.com',
    'smtp_pass' => 'password',
    'smtp_debug' => 2, // 开启调试模式
    'smtp_from_email' => 'sender@example.com',
    'smtp_from_name' => '发件人'
]);

// 调试级别说明：
// 0 = 关闭调试
// 1 = 客户端消息
// 2 = 客户端和服务器消息
// 3 = 连接级别
// 4 = 低级别信息

安全考虑

1. 邮件内容安全

对用户输入进行HTML转义
验证邮箱地址格式
限制邮件内容长度
过滤危险HTML标签

2. SMTP安全

使用SSL/TLS加密连接
定期更换SMTP密码
使用应用专用密码
限制SMTP访问IP

3. 防垃圾邮件

实现发送频率限制
验证收件人邮箱有效性
添加退订链接
遵循反垃圾邮件规范

部署检查清单

环境检查

[ ] PHP版本 >= 8.0
[ ] PHPMailer已安装
[ ] SMTP服务器可访问
[ ] 网络连接正常

系统配置检查

[ ] 邮件功能开关已启用 (email_is_enabled = 1)
[ ] SMTP配置正确 (email_config)
[ ] 邮箱认证信息正确
[ ] 发件人信息配置

通知模板检查

[ ] 邮件通知模板已创建 (sys_notice_tpl)
[ ] 邮件开关已开启 (email_switch = 1)
[ ] 支持渠道包含邮件 (supported_channels 包含 'email')
[ ] 邮件模板内容正确

最后更新：2024-01-20
维护者：DSPlatform技术团队

邮件开发指南 ​

概述 ​

环境要求 ​

1. 依赖安装 ​

2. 系统要求 ​

3. 官方文档 ​

邮件架构 ​

1. 架构图 ​

2. 核心组件 ​

邮件工具类 ​

1. Email类结构 ​

2. 核心功能 ​

系统集成使用 ​

1. 系统通知邮件发送 ​

2. 系统配置 ​

3. 通知模板配置 ​

基础使用 ​

1. 直接使用Email类 ​

2. 发送简单邮件 ​

业务场景应用 ​

1. 用户注册欢迎邮件 ​

2. 密码重置邮件 ​

3. 订单状态通知邮件 ​

配置说明 ​

1. 系统邮件配置 ​

2. SMTP配置参数 ​

3. 常用邮件服务商配置 ​

3.1 QQ邮箱 ​

3.2 163邮箱 ​

3.3 腾讯企业邮箱 ​

3.4 Gmail ​

错误处理 ​

1. 常见错误码 ​

2. 异常处理 ​

3. 调试模式 ​

安全考虑 ​

1. 邮件内容安全 ​

2. SMTP安全 ​

3. 防垃圾邮件 ​

部署检查清单 ​

环境检查 ​

系统配置检查 ​

通知模板检查 ​

邮件开发指南

概述

环境要求

1. 依赖安装

2. 系统要求

3. 官方文档

邮件架构

1. 架构图

2. 核心组件

邮件工具类

1. Email类结构

2. 核心功能

系统集成使用

1. 系统通知邮件发送

2. 系统配置

3. 通知模板配置

基础使用

1. 直接使用Email类

2. 发送简单邮件

业务场景应用

1. 用户注册欢迎邮件

2. 密码重置邮件

3. 订单状态通知邮件

配置说明

1. 系统邮件配置

2. SMTP配置参数

3. 常用邮件服务商配置

3.1 QQ邮箱

3.2 163邮箱

3.3 腾讯企业邮箱

3.4 Gmail

错误处理

1. 常见错误码

2. 异常处理

3. 调试模式

安全考虑

1. 邮件内容安全

2. SMTP安全

3. 防垃圾邮件

部署检查清单

环境检查

系统配置检查

通知模板检查