PHPackages                             tourze/smtp-mailer-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. tourze/smtp-mailer-bundle

ActiveSymfony-bundle[Mail & Notifications](/categories/mail)

tourze/smtp-mailer-bundle
=========================

SMTP Mailer Bundle

0.0.2(4mo ago)00MITPHPCI passing

Since May 29Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/tourze/smtp-mailer-bundle)[ Packagist](https://packagist.org/packages/tourze/smtp-mailer-bundle)[ RSS](/packages/tourze-smtp-mailer-bundle/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (40)Versions (3)Used By (0)

SMTP Mailer Bundle
==================

[](#smtp-mailer-bundle)

[![PHP Version](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)](https://www.php.net/)[![License](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![Build Status](https://camo.githubusercontent.com/5b63f43aa1b7e4eb04322b3e27b56ae58cef2bfe9e13019b2c222a61fa4ba692/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4275696c642d50617373696e672d627269676874677265656e)](https://github.com/tourze/php-monorepo)[![Code Coverage](https://camo.githubusercontent.com/d812aef715b5e8aa174958021726217da78e8b54a7bfdf0dd763df77fbe8a11d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436f7665726167652d39302532352d627269676874677265656e)](https://github.com/tourze/php-monorepo)

[English](README.md) | [中文](README.zh-CN.md)

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

📚 目录
----

[](#-目录)

- [功能特性](#%E5%8A%9F%E8%83%BD%E7%89%B9%E6%80%A7)
- [安装](#%E5%AE%89%E8%A3%85)
- [🚀 快速开始](#-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B)
    - [5分钟快速体验](#5%E5%88%86%E9%92%9F%E5%BF%AB%E9%80%9F%E4%BD%93%E9%AA%8C)
- [配置](#%E9%85%8D%E7%BD%AE)
- [不同环境的配置示例](#%E4%B8%8D%E5%90%8C%E7%8E%AF%E5%A2%83%E7%9A%84%E9%85%8D%E7%BD%AE%E7%A4%BA%E4%BE%8B)
- [使用](#%E4%BD%BF%E7%94%A8)
    - [基本发送](#%E5%9F%BA%E6%9C%AC%E5%8F%91%E9%80%81)
    - [指定SMTP配置发送](#%E6%8C%87%E5%AE%9Asmtp%E9%85%8D%E7%BD%AE%E5%8F%91%E9%80%81)
    - [使用不同的选择策略](#%E4%BD%BF%E7%94%A8%E4%B8%8D%E5%90%8C%E7%9A%84%E9%80%89%E6%8B%A9%E7%AD%96%E7%95%A5)
- [高级用法](#%E9%AB%98%E7%BA%A7%E7%94%A8%E6%B3%95)
    - [自定义 SMTP 选择策略](#%E8%87%AA%E5%AE%9A%E4%B9%89-smtp-%E9%80%89%E6%8B%A9%E7%AD%96%E7%95%A5)
    - [批量邮件发送](#%E6%89%B9%E9%87%8F%E9%82%AE%E4%BB%B6%E5%8F%91%E9%80%81)
    - [邮件模板支持](#%E9%82%AE%E4%BB%B6%E6%A8%A1%E6%9D%BF%E6%94%AF%E6%8C%81)
- [运行定时任务处理](#%E8%BF%90%E8%A1%8C%E5%AE%9A%E6%97%B6%E4%BB%BB%E5%8A%A1%E5%A4%84%E7%90%86)
- [后台管理](#%E5%90%8E%E5%8F%B0%E7%AE%A1%E7%90%86)
- [🔧 故障排除](#-%E6%95%85%E9%9A%9C%E6%8E%92%E9%99%A4)
    - [常见问题](#%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98)
    - [调试模式](#%E8%B0%83%E8%AF%95%E6%A8%A1%E5%BC%8F)
- [⚡ 性能优化](#-%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96)
    - [大批量邮件发送优化](#%E5%A4%A7%E6%89%B9%E9%87%8F%E9%82%AE%E4%BB%B6%E5%8F%91%E9%80%81%E4%BC%98%E5%8C%96)
    - [监控指标](#%E7%9B%91%E6%8E%A7%E6%8C%87%E6%A0%87)
    - [优化建议](#%E4%BC%98%E5%8C%96%E5%BB%BA%E8%AE%AE)
- [🤝 贡献指南](#-%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97)
    - [开发环境设置](#%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E8%AE%BE%E7%BD%AE)
    - [运行测试](#%E8%BF%90%E8%A1%8C%E6%B5%8B%E8%AF%95)
    - [提交规范](#%E6%8F%90%E4%BA%A4%E8%A7%84%E8%8C%83)
    - [报告问题](#%E6%8A%A5%E5%91%8A%E9%97%AE%E9%A2%98)
- [依赖项](#%E4%BE%9D%E8%B5%96%E9%A1%B9)
- [许可证](#%E8%AE%B8%E5%8F%AF%E8%AF%81)

功能特性
----

[](#功能特性)

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

安装
--

[](#安装)

```
composer require tourze/smtp-mailer-bundle
```

🚀 快速开始
------

[](#-快速开始)

### 5分钟快速体验

[](#5分钟快速体验)

1. **安装 Bundle**

    ```
    composer require tourze/smtp-mailer-bundle
    ```
2. **基本配置**

    ```
    # .env
    SMTP_MAILER_DEFAULT_FROM_EMAIL=your@email.com
    ```
3. **发送第一封邮件**

    ```
    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配置发送

[](#指定smtp配置发送)

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

### 使用不同的选择策略

[](#使用不同的选择策略)

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

高级用法
----

[](#高级用法)

### 自定义 SMTP 选择策略

[](#自定义-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
```

⚡ 性能优化
------

[](#-性能优化)

### 大批量邮件发送优化

[](#大批量邮件发送优化)

1. **使用异步处理**

    ```
    SMTP_MAILER_ASYNC_ENABLED=true
    ```
2. **调整处理间隔**

    ```
    SMTP_MAILER_PROCESS_INTERVAL=30
    ```
3. **配置多个 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
```

### 提交规范

[](#提交规范)

请遵循项目的以下规范：

- [PHP 代码规范](../../.cursor/rules/php.mdc)
- [测试规范](../../.cursor/rules/testing.mdc)
- [Git 提交规范](../../.cursor/rules/git.mdc)

### 报告问题

[](#报告问题)

如果发现 Bug 或有功能建议，请在 [GitHub Issues](https://github.com/tourze/php-monorepo/issues) 中提交。

依赖项
---

[](#依赖项)

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

许可证
---

[](#许可证)

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

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance74

Regular maintenance activity

Popularity0

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity28

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~203 days

Total

2

Last Release

142d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e354fdb316da535dfa8ba2e9193a473c403b6bc6fb9170778d1dc50e304c6e9d?d=identicon)[tourze](/maintainers/tourze)

---

Top Contributors

[![tourze](https://avatars.githubusercontent.com/u/13899502?v=4)](https://github.com/tourze "tourze (5 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tourze-smtp-mailer-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/tourze-smtp-mailer-bundle/health.svg)](https://phpackages.com/packages/tourze-smtp-mailer-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M650](/packages/sylius-sylius)[contao/core-bundle

Contao Open Source CMS

1231.6M2.3k](/packages/contao-core-bundle)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)