README

一个功能丰富的 Symfony Bundle，用于管理多个 SMTP 配置并支持灵活的邮件发送策略。

📚 目录

功能特性
安装
🚀 快速开始
- 5分钟快速体验
配置
不同环境的配置示例
使用
高级用法
运行定时任务处理
后台管理
🔧 故障排除
- 常见问题
- 调试模式
⚡ 性能优化
🤝 贡献指南
依赖项
许可证

功能特性

支持配置多个 SMTP 服务器信息
支持邮件发送任务管理，包括定时发送
支持同步/异步发送（通过 symfony/messenger）
提供灵活的 SMTP 服务器选择策略（轮询、随机、权重等）
集成 EasyAdmin 后台管理界面
提供服务层供内部调用

安装

composer require tourze/smtp-mailer-bundle

🚀 快速开始

5分钟快速体验

安装 Bundle

composer require tourze/smtp-mailer-bundle

基本配置

# .env
SMTP_MAILER_DEFAULT_FROM_EMAIL=your@email.com

发送第一封邮件

use Tourze\SMTPMailerBundle\Service\SMTPMailerService;

// 在控制器或服务中
public function sendEmail(SMTPMailerService $mailerService): void
{
    $taskId = $mailerService->send(
        'recipient@example.com',
        'Hello World',
        'Your first email via SMTP Mailer Bundle!'
    );
}

配置

Bundle 通过环境变量进行配置，支持以下配置项：

# 是否启用异步发送（默认：true）
SMTP_MAILER_ASYNC_ENABLED=true

# 默认发件人邮箱（默认：no-reply@example.com）
SMTP_MAILER_DEFAULT_FROM_EMAIL=no-reply@yoursite.com

# 默认SMTP选择策略（默认：round_robin）
# 可选值：round_robin, random, weighted, priority
SMTP_MAILER_DEFAULT_STRATEGY=round_robin

# 计划任务处理间隔，单位秒（默认：60）
SMTP_MAILER_PROCESS_INTERVAL=60

你可以在 .env 文件中设置这些环境变量：

# .env
SMTP_MAILER_ASYNC_ENABLED=true
SMTP_MAILER_DEFAULT_FROM_EMAIL=support@mycompany.com
SMTP_MAILER_DEFAULT_STRATEGY=priority
SMTP_MAILER_PROCESS_INTERVAL=30

不同环境的配置示例

# 开发环境 - 快速处理，同步发送便于调试
export SMTP_MAILER_ASYNC_ENABLED=false
export SMTP_MAILER_DEFAULT_FROM_EMAIL=dev@localhost
export SMTP_MAILER_DEFAULT_STRATEGY=round_robin
export SMTP_MAILER_PROCESS_INTERVAL=10

# 生产环境 - 异步发送，优先级策略
export SMTP_MAILER_ASYNC_ENABLED=true
export SMTP_MAILER_DEFAULT_FROM_EMAIL=noreply@yourcompany.com
export SMTP_MAILER_DEFAULT_STRATEGY=priority
export SMTP_MAILER_PROCESS_INTERVAL=60

# 测试环境 - 同步发送，随机策略
export SMTP_MAILER_ASYNC_ENABLED=false
export SMTP_MAILER_DEFAULT_FROM_EMAIL=test@example.com
export SMTP_MAILER_DEFAULT_STRATEGY=random
export SMTP_MAILER_PROCESS_INTERVAL=30

使用

基本发送

// 注入服务
use Tourze\SMTPMailerBundle\Service\SMTPMailerService;

class MyController extends AbstractController
{
    public function sendEmail(SMTPMailerService $mailerService)
    {
        $mailerService->send(
            'recipient@example.com',
            '邮件主题',
            '邮件内容',
            [
                'from' => 'sender@example.com',
                'isHtml' => true,
                'cc' => ['cc@example.com'],
            ]
        );
        
        // 或者安排稍后发送
        $mailerService->send(
            'recipient@example.com',
            '定时邮件',
            '这是一封定时发送的邮件',
            [
                'scheduledAt' => new \DateTime('+1 hour')
            ]
        );
    }
}

指定SMTP配置发送

// 使用特定ID的SMTP配置
$mailerService->sendWithConfig(
    $smtpConfigId,
    'recipient@example.com',
    '邮件主题',
    '邮件内容'
);

使用不同的选择策略

// 使用优先级策略选择SMTP
$mailerService->send(
    'recipient@example.com',
    '邮件主题',
    '邮件内容',
    [
        'strategy' => 'priority'
    ]
);

高级用法

自定义 SMTP 选择策略

use Tourze\SMTPMailerBundle\Service\SMTPSelector\SMTPSelectorStrategyInterface;
use Tourze\SMTPMailerBundle\Entity\SMTPConfig;

class MyCustomStrategy implements SMTPSelectorStrategyInterface
{
    public function selectConfig(array $configs): ?SMTPConfig
    {
        // 实现自定义选择逻辑
        return $configs[array_rand($configs)] ?? null;
    }
}

批量邮件发送

$tasks = [];
foreach ($recipients as $recipient) {
    $tasks[] = $mailerService->send(
        $recipient['email'],
        '批量邮件',
        '邮件内容',
        ['async' => true]
    );
}

邮件模板支持

$mailerService->send(
    'recipient@example.com',
    '模板邮件',
    $this->renderView('emails/welcome.html.twig', [
        'user' => $user
    ]),
    [
        'isHtml' => true,
        'attachments' => [
            [
                'name' => 'attachment.pdf',
                'mime' => 'application/pdf',
                'data' => base64_encode($pdfContent)
            ]
        ]
    ]
);

运行定时任务处理

为了处理定时邮件任务，需要设置一个 cron 任务或使用 Symfony Messenger worker:

# 处理定时邮件
php bin/console smtp-mailer:process-scheduled-mails

# 如果使用异步处理，需要运行 messenger worker
php bin/console messenger:consume async

后台管理

Bundle 使用 EasyAdmin 提供管理界面，访问 /admin 即可管理 SMTP 配置和邮件任务。

🔧 故障排除

常见问题

Q: 邮件发送失败，提示连接超时

A: 检查 SMTP 服务器配置和网络连接，确保端口未被防火墙阻止。

# 测试 SMTP 连接
telnet smtp.example.com 587

Q: 异步邮件没有发送

A: 确保运行了 messenger worker：

php bin/console messenger:consume async

Q: 定时邮件没有执行

A: 检查 cron 任务是否正确配置：

# 添加到 crontab
* * * * * cd /path/to/project && php bin/console smtp-mailer:process-scheduled-mails

Q: 邮件发送到垃圾箱

A: 检查以下设置：

SPF 记录配置
DKIM 签名设置
发件人域名信誉
邮件内容合规性

调试模式

启用详细日志来诊断问题：

# .env
APP_ENV=dev
SYMFONY_LOG_LEVEL=debug

⚡ 性能优化

大批量邮件发送优化

使用异步处理
```
SMTP_MAILER_ASYNC_ENABLED=true
```
调整处理间隔
```
SMTP_MAILER_PROCESS_INTERVAL=30
```

配置多个 SMTP 服务器实现负载均衡

// 在后台管理中添加多个 SMTP 配置
// 使用加权策略分配流量

监控指标

建议监控以下指标：

邮件发送成功率
平均发送延迟
SMTP 服务器状态
队列积压情况

优化建议

对于大量邮件，建议分批发送避免服务器压力
使用 Redis 作为 Messenger transport 提高性能
定期清理已发送的邮件任务记录

🤝 贡献指南

我们欢迎任何形式的贡献！

开发环境设置

git clone https://github.com/tourze/php-monorepo.git
cd php-monorepo/packages/smtp-mailer-bundle
composer install

运行测试

# 运行单元测试
./vendor/bin/phpunit

# 运行代码质量检查
php -d memory_limit=2G ./vendor/bin/phpstan analyse

# 运行代码格式检查
./vendor/bin/php-cs-fixer fix --dry-run

提交规范

请遵循项目的以下规范：

报告问题

如果发现 Bug 或有功能建议，请在 GitHub Issues 中提交。

依赖项

PHP 8.1+
Symfony 6.4+
Doctrine ORM 3.0+
Symfony Messenger（用于异步处理）

许可证

此 Bundle 基于 MIT 许可证。详情请查看 LICENSE 文件。

tourze / smtp-mailer-bundle

Maintainers

Details