PHPackages                             cyzonetech/tp-mailer - 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. cyzonetech/tp-mailer

ActiveLibrary[Mail & Notifications](/categories/mail)

cyzonetech/tp-mailer
====================

A powerful and beautiful php mailer for All of ThinkPHP and Other PHP Frameworks based SwiftMailer

v0.2.6(7y ago)1269Apache 2.0PHPPHP >=5.4.0

Since Nov 30Pushed 7y agoCompare

[ Source](https://github.com/cyzonetech/tp-mailer)[ Packagist](https://packagist.org/packages/cyzonetech/tp-mailer)[ Docs](https://github.com/yuan1994/tp-mailer/)[ RSS](/packages/cyzonetech-tp-mailer/feed)WikiDiscussions master Synced yesterday

READMEChangelog (2)Dependencies (1)Versions (9)Used By (0)

Tp Mailer
---------

[](#tp-mailer)

**一款支持所有PHP框架的优美的邮件发送类**，ThinkPHP系列框架开箱即用，其他框架初始化配置即可使用

基于 SwiftMailer 二次开发, 为 ThinkPHP系列框架量身定制, 使 ThinkPHP 支持邮件模板、纯文本、附件邮件发送以及更多邮件功能, 邮件发送简单到只需一行代码

同时了方便其他框架或者非框架使用, Tp Mailer也非常容易拓展融合到其他框架中, 欢迎大家 `Fork` 和 `Star`, 提交代码让Tp Mailer支持更多框架

目录
--

[](#目录)

- [优雅的发送邮件](#%E4%BC%98%E9%9B%85%E7%9A%84%E5%8F%91%E9%80%81%E9%82%AE%E4%BB%B6)
- [安装](#%E5%AE%89%E8%A3%85)
    - [使用 Composer 安装 (强烈推荐)](#%E4%BD%BF%E7%94%A8-composer-%E5%AE%89%E8%A3%85-%E5%BC%BA%E7%83%88%E6%8E%A8%E8%8D%90)
    - [github下载 或 直接手动下载源码](#github%E4%B8%8B%E8%BD%BD-%E6%88%96-%E7%9B%B4%E6%8E%A5%E6%89%8B%E5%8A%A8%E4%B8%8B%E8%BD%BD%E6%BA%90%E7%A0%81)
        - [下载文件](#%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6)
        - [移动文件夹](#%E7%A7%BB%E5%8A%A8%E6%96%87%E4%BB%B6%E5%A4%B9)
        - [引入自动载入文件](#%E5%BC%95%E5%85%A5%E8%87%AA%E5%8A%A8%E8%BD%BD%E5%85%A5%E6%96%87%E4%BB%B6)
- [配置](#%E9%85%8D%E7%BD%AE)
    - [部分配置详解](#%E9%83%A8%E5%88%86%E9%85%8D%E7%BD%AE%E8%AF%A6%E8%A7%A3)
- [使用](#%E4%BD%BF%E7%94%A8)
    - [使用Tp Mailer](#%E4%BD%BF%E7%94%A8tp-mailer)
    - [创建实例](#%E5%88%9B%E5%BB%BA%E5%AE%9E%E4%BE%8B)
    - [设置收件人](#%E8%AE%BE%E7%BD%AE%E6%94%B6%E4%BB%B6%E4%BA%BA)
    - [设置发件人](#%E8%AE%BE%E7%BD%AE%E5%8F%91%E4%BB%B6%E4%BA%BA)
    - [设置邮件主题](#%E8%AE%BE%E7%BD%AE%E9%82%AE%E4%BB%B6%E4%B8%BB%E9%A2%98)
    - [设置邮件内容 - HTML](#%E8%AE%BE%E7%BD%AE%E9%82%AE%E4%BB%B6%E5%86%85%E5%AE%B9---html)
    - [设置邮件内容 - 纯文本](#%E8%AE%BE%E7%BD%AE%E9%82%AE%E4%BB%B6%E5%86%85%E5%AE%B9---%E7%BA%AF%E6%96%87%E6%9C%AC)
    - [设置邮件内容 - 模板](#%E8%AE%BE%E7%BD%AE%E9%82%AE%E4%BB%B6%E5%86%85%E5%AE%B9---%E6%A8%A1%E6%9D%BF)
    - [将图片作为元数据嵌入到邮件中](#%E5%B0%86%E5%9B%BE%E7%89%87%E4%BD%9C%E4%B8%BA%E5%85%83%E6%95%B0%E6%8D%AE%E5%B5%8C%E5%85%A5%E5%88%B0%E9%82%AE%E4%BB%B6%E4%B8%AD)
        - [配置嵌入标签](#%E9%85%8D%E7%BD%AE%E5%B5%8C%E5%85%A5%E6%A0%87%E7%AD%BE)
        - [模板或HTML中设置变量](#%E6%A8%A1%E6%9D%BF%E6%88%96html%E4%B8%AD%E8%AE%BE%E7%BD%AE%E5%8F%98%E9%87%8F)
        - [传递变量参数和值](#%E4%BC%A0%E9%80%92%E5%8F%98%E9%87%8F%E5%8F%82%E6%95%B0%E5%92%8C%E5%80%BC)
        - [示例](#%E7%A4%BA%E4%BE%8B)
    - [添加附件](#%E6%B7%BB%E5%8A%A0%E9%99%84%E4%BB%B6)
    - [设置消息加密/签名](#%E8%AE%BE%E7%BD%AE%E6%B6%88%E6%81%AF%E5%8A%A0%E5%AF%86%E7%AD%BE%E5%90%8D)
    - [设置字符编码](#%E8%AE%BE%E7%BD%AE%E5%AD%97%E7%AC%A6%E7%BC%96%E7%A0%81)
    - [设置邮件最大长度](#%E8%AE%BE%E7%BD%AE%E9%82%AE%E4%BB%B6%E6%9C%80%E5%A4%A7%E9%95%BF%E5%BA%A6)
    - [设置邮件优先级](#%E8%AE%BE%E7%BD%AE%E9%82%AE%E4%BB%B6%E4%BC%98%E5%85%88%E7%BA%A7)
    - [Requesting a Read Receipt](#requesting-a-read-receipt)
    - [注册插件](#%E6%B3%A8%E5%86%8C%E6%8F%92%E4%BB%B6)
    - [发送邮件](#%E5%8F%91%E9%80%81%E9%82%AE%E4%BB%B6)
- [动态配置](#%E5%8A%A8%E6%80%81%E9%85%8D%E7%BD%AE)
- [方法注入](#%E6%96%B9%E6%B3%95%E6%B3%A8%E5%85%A5)
- [其他框架扩展](#%E5%85%B6%E4%BB%96%E6%A1%86%E6%9E%B6%E6%89%A9%E5%B1%95)
    - [第一步: 初始化配置项](#%E7%AC%AC%E4%B8%80%E6%AD%A5-%E5%88%9D%E5%A7%8B%E5%8C%96%E9%85%8D%E7%BD%AE%E9%A1%B9)
    - [第二步: 实现 `$mailer->view()` 方法](#%E7%AC%AC%E4%BA%8C%E6%AD%A5-%E5%AE%9E%E7%8E%B0-mailer-view-%E6%96%B9%E6%B3%95)
    - [完整示例](#%E5%AE%8C%E6%95%B4%E7%A4%BA%E4%BE%8B)
- [中文文件名乱码问题](#%E4%B8%AD%E6%96%87%E6%96%87%E4%BB%B6%E5%90%8D%E4%B9%B1%E7%A0%81%E9%97%AE%E9%A2%98)
- [Issues](#issues)
- [License](#license)

优雅的发送邮件
-------

[](#优雅的发送邮件)

**ThinkPHP5 示例**

```
use mailer\tp5\Mailer;

$mailer = Mailer::instance();
$mailer->from('tianpian0805@gmail.com', 'yuan1994')
    ->to('your-mail@domain.com')
    ->subject('纯文本测试')
    ->text('欢迎您使用Tp Mailer')
    ->send();

```

你也可以这样: **ThinkPHP3.2.3 示例**

```
require_once '/path/to/tp-mailer/src/autoload.php';

use mailer\tp32\Mailer;

$mailer = Mailer::instance();
$mailer->from('tianpian0805@gmail.com', 'yuan1994')
    ->to('your-mail@domain.com')
    ->subject('多行文本测试')
    ->line('PHPer们: ')
    ->line('欢迎你们使用Tp Mailer, 如果使用感觉很方面请给个Star, 也欢迎大家Fork帮忙完善')
    ->line()
    ->line('yuan1994  'smtp', // 邮件驱动, 支持 smtp|sendmail|mail 三种驱动
        'host'            => 'smtp.qq.com', // SMTP服务器地址
        'port'            => 465, // SMTP服务器端口号,一般为25
        'addr'            => '', // 发件邮箱地址
        'pass'            => '', // 发件邮箱密码
        'name'            => '', // 发件邮箱名称
        'content_type'    => 'text/html', // 默认文本内容 text/html|text/plain
        'charset'         => 'utf-8', // 默认字符集
        'security'        => 'ssl', // 加密方式 null|ssl|tls, QQ邮箱必须使用ssl
        'sendmail'        => '/usr/sbin/sendmail -bs', // 不适用 sendmail 驱动不需要配置
        'debug'           => true, // 开启debug模式会直接抛出异常, 记录邮件发送日志
        'left_delimiter'  => '{', // 模板变量替换左定界符, 可选, 默认为 {
        'right_delimiter' => '}', // 模板变量替换右定界符, 可选, 默认为 }
        'log_driver'      => '', // 日志驱动类, 可选, 如果启用必须实现静态 public static function write($content, $level = 'debug') 方法
        'log_path'        => '', // 日志路径, 可选, 不配置日志驱动时启用默认日志驱动, 默认路径是 /path/to/tp-mailer/log, 要保证该目录有可写权限, 最好配置自己的日志路径
        'embed'           => 'embed:', // 邮件中嵌入图片元数据标记
];

```

### 部分配置详解

[](#部分配置详解)

#### driver

[](#driver)

可选值可以是字符串、数组、对象。如果是字符串，只能是 `smtp|sendmail|mail`，即内置的三种邮件驱动；如果是数组，必须是可以实例调用的方法，例如 `['mailer\\lib\\Transport', 'createSmtpDriver']` ，即是调用的 `(new mailer\lib\Transport)->createSmtpDriver()` 方法，如果是对象，就是返回的一个 `Swift_Transport` 对象，详情请查看 SwiftMailer 官网

#### log\_left\_delimiter & right\_delimiter

[](#log_left_delimiter--right_delimiter)

该值为内置模板变量 (调用`text()`,`raw()`,`line()`,`html()`方式时传递的变量) 定界值，例如默认定界值时 `{name}`， 如果变量为 `['name' => 'tp-mailer']`，那么 `{name}` 会被替换为 `tp-mailer`，加入模板中变量占位符是 `{$name}`，那么此时可以修改左定界符为 `{$`，此时 `{$name}` 也能被正常替换为 `tp-mailer`

#### log\_driver

[](#log_driver)

日志驱动，如果不配置则为类库自带简单的日志驱动 `mailer\lib\log\File`，可自定义配置为框架的日志驱动，例如 `'log_driver' => '\\think\\Log'`，日志驱动类必须实现静态方法 `write`，例如:

```
public static function write($content, $level = 'debug')
{
    echo '日志内容：' . $content;
    echo '日志级别：' . $level;
}

```

#### log\_path

[](#log_path)

日志驱动为默认是日志存储路径，不配置默认为 `tp-mailer/log/`，例如可配置为 `ROOT_PATH . 'runtime/log/'`

#### embed

[](#embed)

图片内联嵌入标识，请参考 [将图片作为元数据嵌入到邮件中](#%E5%B0%86%E5%9B%BE%E7%89%87%E4%BD%9C%E4%B8%BA%E5%85%83%E6%95%B0%E6%8D%AE%E5%B5%8C%E5%85%A5%E5%88%B0%E9%82%AE%E4%BB%B6%E4%B8%AD)

使用
--

[](#使用)

> 以下使用及方法兼容所有框架, 包括 ThinkPHP5, ThinkPHP3.2, ThinkPHP3.1, 唯一有所区别的是 ThinkPHP3.2 和 ThinkPHP3.1 不支持composer自动载入, 需手动引入自动载入文件, 使用时引入或者全局自动引入:

> `require_once '/path/to/tp-mailer/src/autoload.php';`

> 使用use时, ThinkPHP5 的Mailer类的命名空间是 `mailer/tp5/Mailer`, ThinkPHP3.2 的命名空间是 `mailer/tp32/Mailer`, ThinkPHP3.1 的命名空间是 `mailer/tp31/Mailer`

以下示例以 ThinkPHP5 里使用为例, 其他框架完全一样

### 使用Tp Mailer

[](#使用tp-mailer)

```
// 不支持自动载入的框架请手动引入自动载入文件
// require_once '/path/to/tp-mailer/src/autoload.php';

use mailer\tp5\Mailer

```

### 创建实例

[](#创建实例)

不传递任何参数表示邮件驱动使用配置文件里默认的配置

```
$mailer = Mailer::instance();

```

如果你想实例化时不使用配置文件里的默认配置, 你可以这样:

```
$mailer = Mailer::instance(function() {
    return \Swift_SmtpTransport::newInstance(
            'host', 'port', 'security'
        )
        ->setUsername($config['addr'])
        ->setPassword($config['pass']);
});

```

匿名必须返回一个 `\Swift_SmtpTransport` 或 `\Swift_SendmailTransport` 或 `\Swift_MailTransport`, 详细配置请参考 [SwiftMailer Transport Types](http://swiftmailer.org/docs/sending.html#transport-types)

你也可以直接手动传入一个现有的邮件驱动, 配置使用默认配置, 像这样:

```
$mailer = Mailer::instance('sendmail');

```

### 设置收件人

[](#设置收件人)

以下几种方式任选一种

```
$mailer->to(['tianpian0805@gmail.com']);
$mailer->to(['tianpian0805@gmail.com' => 'yuan1994']);
$mailer->to('tianpian0805@gmail.com', 'yuan1994');
$mailer->to(['tianpian0805@qq.com', 'tianpian0805@gmail.com' => 'yuan1994']);
$mailer->to(['tianpian0805@qq.com', 'tianpian0805@gmail.com', 'tianpian0805@163.com']);

```

### 设置发件人

[](#设置发件人)

发件人邮箱地址必须和配置项里一致, 默认会自动设置发件地址 (配置里的addr) 和发件人 (配置里的name)

```
$mailer->from('tianpian0805@gmail.com', 'yuan1994');
$mailer->from(['tianpian0805@gmail.com' => 'yuan1994']);

```

### 设置邮件主题

[](#设置邮件主题)

```
$mailer->subject('邮件主题');

```

### 设置邮件内容 - HTML

[](#设置邮件内容---html)

```
$mailer->html('欢迎使用Tp Mailer');

```

或者使用变量替换HTML内容

```
$mailer->html('欢迎使用{name}', ['name' => 'Tp Mailer']);

```

### 设置邮件内容 - 纯文本

[](#设置邮件内容---纯文本)

```
$mailer->text('欢迎使用Tp Mailer');

```

还有另外一个用法完全相同的同名方法

```
$mailer->raw('欢迎使用Tp Mailer');

```

或者使用变量替换纯文本内容

```
$mailer->text('欢迎使用{name}', ['name' => 'Tp Mailer']);

```

你也可以很方便的设置多行文本, 直接回车换行或者使用 `line()` 方法, 支持多次调用

```
$mailer->line('尊敬的 访客: ');
$mailer->line('   欢迎您使用Tp Mailer');
$mailer->line(); // 不传值默认输出空行
$mailer->line('yuan1994 ' . date('Y-m-d') );
// 以上历程输出
/***************
尊敬的 访客:
   欢迎您使用Tp Mailer

yuan1994 2016-12-01
****************/

```

`line()` 也支持使用变量替换纯文本内容

```
$mailer->text('欢迎使用{name}', ['name' => 'Tp Mailer']);

```

### 设置邮件内容 - 模板

[](#设置邮件内容---模板)

ThinkPHP系列模板, 具体请看ThinkPHP各版本框架的模板怎么用, 第二个参数是要进行模板赋值的数组

```
$mailer->view('mail/register');
$mailer->view('admin@mail/register', ['account' => $account, 'name' => $name]);

```

### 将图片作为元数据嵌入到邮件中

[](#将图片作为元数据嵌入到邮件中)

邮件内容中包含图片的, 可以直接指定 `img` 标签的 `src` 属性为远程图片地址, 此处图片地址必须为远程图片地址, 必须为一个带域名的完整图片链接, 这似乎很麻烦, 所以你还可以将图片作为元数据嵌入到邮件中, 至于其他文件是否也可以嵌入请自己尝试, 详情请参考 [SwiftMailer Embedding Inline Media Files](http://swiftmailer.org/docs/messages.html#embedding-inline-media-files)

下面介绍一下 `tp-mailer` 如何快速简便的将图片元数据嵌入到邮件中:

#### 配置嵌入标签

[](#配置嵌入标签)

嵌入元数据需要在模板赋值或者使用 `html()` 传递变量时, 给变量添加特殊的标签, 该嵌入标签默认为 `embed:`, 你可以修改配置文件中 `embed` 项, 修改为你想要的形式

#### 模板或HTML中设置变量

[](#模板或html中设置变量)

在模板中, 例如 ThinkPHP 全系列都是使用 `{$var}` 的形式传递变量, 假设变量为 `image_src`, 那么模板中填写 `{$image_src}`, 如果是在HTML中, 请使用 `{image_src}`, 注意如果修改过左、右定界符请使用自己定义的左右定界符

#### 传递变量参数和值

[](#传递变量参数和值)

在 `html()` 和 `view()` 方法的第二个参数里, 该数组必须有一个变量, 格式为 `['embed:image_src'] => '/path/to/image.jpg']` 或者 `['embed:image_src'] => ['file_stream', 'filemime', 'filename']]`, 即参数数组的键名是上面配置的 `嵌入标签 + 变量名`, 但值有两种情况:

第一, 如果值为字符串, 则该值为图片的路径 (绝对路径或相对路径) 或者 有效的url地址;

第二, 如果值为数组, 数组为 `['stream', 'mime', 'name']` 的形式, 其中 `stream` 表示图片的数据流, 即是未保存的文件数据流, 例如 `file_get_contents()` 方法获取的文件数据流, 第二个参数可选, 为文件的mime类型, 默认为 `image/jpeg`, 第三个参数为文件名, 默认为 `image.jpg`

#### 示例

[](#示例)

```
Mailer::instance()
    ->to('tianpian0805@gmail.com', 'yuan1994')
    ->subject('测试邮件模板中嵌入图片元数据')
    ->view('index@mail/index', [
        'date' => date('Y-m-d H:i:s'),
        'embed:image' => ROOT_PATH . 'image.jpg',
        // 'embed:image' => 'http://image34.360doc.com/DownloadImg/2011/08/2222/16275597_64.jpg',
        // 'embed:image' => [file_get_contents(ROOT_PATH . 'image1.jpg')],
        // 'embed:image' => [file_get_contents(ROOT_PATH . 'image1.jpg', 'image/png', '图片.png')],
     ])
    ->send();

```

其中模板的内容如下:

```

    测试邮件

尊敬的yuan1994:
     这是一封模板测试邮件
{$date}

```

在 HTML 中使用一样:

```
Mailer::instance()
    ->to('tianpian0805@gmail.com', 'yuan1994')
    ->subject('测试邮件模板中嵌入图片元数据')
    ->html('图片测试', [
        'embed:image' => ROOT_PATH . 'image.jpg',
        // 'embed:image' => 'http://image34.360doc.com/DownloadImg/2011/08/2222/16275597_64.jpg',
        // 'embed:image' => [file_get_contents(ROOT_PATH . 'image1.jpg')],
        // 'embed:image' => [file_get_contents(ROOT_PATH . 'image1.jpg', 'image/png', '图片.png')],
     ])
    ->send();

```

### 添加附件

[](#添加附件)

已修复SwiftMailer设置中文文件名出现乱码的bug

```
$mailer->attach('http://domain.com/path/to/file.ext');

```

或者指定附件的文件名

```
$mailer->attach(ROOT_PATH . 'foo.ext', '文件名.pdf');

```

使用匿名函数 $attachment用法请参考 [SwiftMailer Attaching Files](http://swiftmailer.org/docs/messages.html#attaching-files)

```
$mailer->attach(ROOT_PATH . 'foo.ext', function($attachment, $mailer) {
    $attachment->setFilename($mailer->cnEncode('文件名.jpg'));
});

```

### 设置消息加密/签名

[](#设置消息加密签名)

使用方法请参考 [SwiftMailer Signed/Encrypted Message](http://swiftmailer.org/docs/messages.html#signed-encrypted-message)

```
$mailer->signCertificate(function() {
    // $signer->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem');
    // $signer->setSignCertificate('/path/to/certificate.pem', array('/path/to/private-key.pem', 'passphrase'));
    // $signer->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem', PKCS7_BINARY);

    $smimeSigner->setSignCertificate('/path/to/sign-certificate.pem', '/path/to/private-key.pem');
    $smimeSigner->setEncryptCertificate('/path/to/encrypt-certificate.pem');
});

```

### 设置字符编码

[](#设置字符编码)

```
$mailer->charset('utf8');

```

### 设置邮件最大长度

[](#设置邮件最大长度)

```
$mailer->lineLength(1000);

```

### 设置邮件优先级

[](#设置邮件优先级)

```
$mailer->priority(MailerConfig::PRIORITY_HIGHEST);
// 可选值有:
// MailerConfig::PRIORITY_HIGHEST
// MailerConfig::PRIORITY_HIGH
// MailerConfig::PRIORITY_NORMAL
// MailerConfig::PRIORITY_LOW
// MailerConfig::PRIORITY_LOWEST

```

> `MailerConfig` 的完整命名空间为 `mailer/lib/MailerConfig`

### Requesting a Read Receipt

[](#requesting-a-read-receipt)

```
$mailer->readReceiptTo('tianpian0805@gamil.com');

```

### 注册插件

[](#注册插件)

```
// Use AntiFlood to re-connect after 100 emails
$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100));

// And specify a time in seconds to pause for (30 secs)
$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100, 30));

```

插件的详细使用请参考 [SwiftMailer Plugins](http://swiftmailer.org/docs/plugins.html)

### 发送邮件

[](#发送邮件)

```
$mailer->send();

```

使用匿名函数, $mailer是 `Mailer` 对象, $message是 `Swift_Message` 对象

```
$mailer->send(function ($mailer, $message) {
    $mailer->to('tianpian0805@gmail.com')
        ->line('你好')
        ->line('这是一封测试邮件')
        ->subject('测试邮件');
});

```

第二个参数也可以是`匿名函数` 或 `字符串` 或 `null`, 用户指定发送邮件使用的驱动, 详细使用请参考本文档的 [创建实例](#%E5%88%9B%E5%BB%BA%E5%AE%9E%E4%BE%8B)

```
$mailer->send(
    function ($mailer, $message) {
        $mailer->to('tianpian0805@gmail.com')
            ->line('你好')
            ->line('这是一封测试邮件')
            ->subject('测试邮件');
            },
    function () {
        return \Swift_SmtpTransport::newInstance(
                    'host', 'port', 'security'
                )
                ->setUsername($config['addr'])
                ->setPassword($config['pass']);
    });

```

如果你使用了插件, 你还可以使用第三个参数, 第三个参数只能是匿名函数:

```
$mailer->send(
    function ($mailer, $message) {
        $mailer->to('tianpian0805@gmail.com')
            ->line('你好')
            ->line('这是一封测试邮件')
            ->subject('测试邮件');
            },
    null,
    function ($swiftMailer, $mailer) use ($lotsOfRecipients {
        // Continue sending as normal
        for ($lotsOfRecipients as $recipient) {
          // $swiftMailer->send($mailer->message, $fails);
          $swiftMailer->send($mailer->message);
        }
    });

```

第三个参数匿名函数里必须使用 `$swiftMailer` 调用 `send()` 方法发送邮件, 并且第一个参数必须为 `$mailer->message`, 插件的详细使用请参考 [SwiftMailer Plugins](http://swiftmailer.org/docs/plugins.html)

除使用插件, `send()` 方法第三个参数为匿名函数的情况外, 发送邮件的返回值为发送成功用户的数字, 全部失败为0, 全部成功为设置收件人的数量

以上所有方法 (除最后发送的方法 `send()`) 都支持连贯调用

```
$mailer->to('tianpian0805@gmail.com')
    ->subject('邮件主题')
    ->text('邮件内容')
    ->send();

```

如果执行过邮件发送过邮件发送之后, 需要重新初始化

```
// 第一次发送
$mailer->to('tianpian0805@gmail.com')
    ->subject('邮件主题')
    ->text('邮件内容')
    ->send();

// 接着进行第二次发送
$mailer->init();
// 或者直接连贯调用
$mailer->init()->to()->...->send();

```

开启 `debug` 模式后, 邮件发送失败会直接以异常抛出, 如果没有开启, 可以通过 `getError()` 获取错误信息

```
$mailer->getError();

```

如果有邮件发送失败, 可以通过 `getFails()` 获取发送失败邮件地址的列表, 邮件发送时第三个参数使用哦匿名函数的情况除外, 这种情况获取到的值为空, 需调用 `$swiftMailer->send()` 时第二个参数手动指定 `fails`

```
$mailer->getFails();
// 如果没有数据将输出空数组, 如果有数据将返回邮件列表数组, 例如
// array('example1@damain.com', 'example2@damain.com')

```

使用 `getHeaders()` 和 `getHeadersString()` 方法可以获取头信息 `getHeaders()` 返回的是头信息数组, `getHeadersString()` 返回的是头信息字符串

更多文档请参考 [SwiftMailer](http://swiftmailer.org/docs/)

动态配置
----

[](#动态配置)

`mailer/lib/Config` 可以进行邮件动态配置，可以读取配置或者重新设置默认配置项，也可以用于其他非 ThinkPHP 框架进行配置项初始化

```
class Config
{
    /**
     * 初始化配置项
     *
     * @param array $config 请参考配置项里的配置格式，其他非ThinkPHP框架不支持自动探测自动初始化配置项，务必使用该方法初始化配置项
     */
    public static function init($config = [])
    {
    }

    /**
     * 获取配置参数 为空则获取所有配置
     *
     * @param string $name    配置参数名
     * @param mixed  $default 默认值
     *
     * @return mixed
     */
    public static function get($name = null, $default = null)
    {
    }

    /**
     * 设置配置参数
     *
     * @param string|array $name  配置参数名
     * @param mixed        $value 配置值
     */
    public static function set($name, $value)
    {
    }
}

```

方法注入
----

[](#方法注入)

`mailer\lib\Mailer` 默认不带 `view()` 方法，但要扩展该类，可以使用继承，也可以直接动态给该类注册方法，使用 `Mailer::addMethod($methodName, $methodCallable)` 进行方法注册，例如给 ThinkPHP5 框架注册 `view()` 方法：

```
use mailer\lib\Mailer
use think\View

Mailer::addMethod('view', function ($template, $param = [], $config = [])
{
    $view = View::instance(Config::get('template'), Config::get('view_replace_str'));
    // 处理变量中包含有对元数据嵌入的变量
    foreach ($param as $k => $v) {
        $this->embedImage($k, $v, $param);
    }
    $content = $view->fetch($template, $param, [], $config);

    return $this->html($content);
});

// 不用use mailer\tp5\Mailer，直接使用mailer\lib\Mailer调用view方法发送邮件
$ret = Mailer::instance()
        ->to('tianpian0805@gmail.com')
        ->subject('测试邮件')
        ->view('index@mail/index', [
            'date' => date('Y-m-d H:i:s'),
        ])
        ->send();

```

你也可以根据需要注入其他方法

其他框架扩展
------

[](#其他框架扩展)

其他框架扩展只需两步, 部署安装使用和文档一样

### 第一步: 初始化配置项

[](#第一步-初始化配置项)

使用 `mailer\lib\Config` 的 `init()` 方法初始化配置项，例如：

```
use mailer\lib\Config

// 配置格式参见前面的配置
$config = [
    'driver' => 'smtp',
    'host'   => 'smtp.qq.com',
    ...
    ];

Config::init($config);

```

### 第二步: 实现 `$mailer->view()` 方法

[](#第二步-实现-mailer-view-方法)

写自己的类继承 `mailer\lib\Mailer` 或者 使用 `Mailer::addMethod()` 方法动态注入方法, 然后实现里面的 `view` 方法, 根据自己的框架渲染出自己的模板，如果不需要使用 `view()` 方法可以忽略这一步，直接进入下一步:

```
/**
 * 载入一个模板作为邮件内容
 *
 * @param string $template
 * @param array  $param
 * @param array  $config
 *
 * @return Mailer
 */
public function view($template, $param = [], $config = [])
{
    $view = View::instance(ThinkConfig::get('template'), ThinkConfig::get('view_replace_str'));
    // 处理变量中包含有对元数据嵌入的变量
    foreach ($param as $k => $v) {
        $this->embedImage($k, $v, $param);
    }
    $content = $view->fetch($template, $param, [], $config);

    return $this->html($content);
}

```

### 完整示例

[](#完整示例)

```
use mailer\lib\Config
use mailer\lib\Mailer

// 第一步：初始化配置项
// 配置格式参见前面的配置
$config = [
    'driver' => 'smtp',
    'host'   => 'smtp.qq.com',
    ...
    ];

Config::init($config);

// 第二步：注册view方法
Mailer::addMethod('view', function ($template, $param = [], $config = [])
{
    $view = \think\View::instance(Config::get('template'), Config::get('view_replace_str'));
    // 处理变量中包含有对元数据嵌入的变量
    foreach ($param as $k => $v) {
        $this->embedImage($k, $v, $param);
    }
    $content = $view->fetch($template, $param, [], $config);

    return $this->html($content);
});

// 第三步：发送邮件
$ret = Mailer::instance()
        ->to('tianpian0805@gmail.com')
        ->subject('测试邮件')
        ->view('index@mail/index', [
            'date' => date('Y-m-d H:i:s'),
        ])
        ->send();

// 第三步 (2)：如果你不需要使用view方法，可以忽略第二步
$ret = Mailer::instance()
        ->to('tianpian0805@gmail.com')
        ->subject('测试邮件')
        ->html('图片测试', [
            'embed:image' => 'http://image34.360doc.com/DownloadImg/2011/08/2222/16275597_64.jpg'
        ])
        ->send();

```

OK, 此时你就能在你的框架中使用 Tp Mailer 了, 如果你还想做一件事 - Fork && Pull, 那就更好, 希望能一起完善 Tp Mailer

中文文件名乱码问题
---------

[](#中文文件名乱码问题)

经测试给邮件添加附件时如果附件时中文名会乱码, 如果添加附件时使用匿名闭包函数, 设置文件名时一定要使用 `cnEncode()` 方法对文件名进行处理, 否则收到的邮件中中文名会乱码, 其他的添加附件方法都在代码里默认调用了 `cnEncode()` 方法

```
// 以下两种形式会自动对文件名进行处理防止乱码
$mailer->attach('http://domain.com/path/to/file.ext');
$mailer->attach(ROOT_PATH . 'foo.ext', '文件名.pdf');

// 使用匿名函数时需手动对中文文件名进行处理
$mailer->attach(ROOT_PATH . 'foo.ext', function($attachment, $mailer) {
    $attachment->setFilename($mailer->cnEncode('文件名.jpg'));
}

```

Issues
------

[](#issues)

如果有遇到问题请提交 [issues](https://github.com/yuan1994/tp-mailer/issues)

License
-------

[](#license)

Apache 2.0

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 75% 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 ~91 days

Recently: every ~158 days

Total

8

Last Release

2810d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3ef3569ae46017080f8b5991b777151e843af273ee124f0cd65f6cffa6cb0cfd?d=identicon)[cyzonetech](/maintainers/cyzonetech)

---

Top Contributors

[![yuan1994](https://avatars.githubusercontent.com/u/10416700?v=4)](https://github.com/yuan1994 "yuan1994 (12 commits)")[![cyzonetech](https://avatars.githubusercontent.com/u/30819954?v=4)](https://github.com/cyzonetech "cyzonetech (4 commits)")

---

Tags

mailmailerswiftmailerthinkphpphpmailertp-mailertp5-mailertp

### Embed Badge

![Health badge](/badges/cyzonetech-tp-mailer/health.svg)

```
[![Health](https://phpackages.com/badges/cyzonetech-tp-mailer/health.svg)](https://phpackages.com/packages/cyzonetech-tp-mailer)
```

###  Alternatives

[yuan1994/tp-mailer

A powerful and beautiful php mailer for All of ThinkPHP and Other PHP Frameworks based SwiftMailer

812.0k1](/packages/yuan1994-tp-mailer)[cattong/think-mailer

A powerful and beautiful php mailer for All of ThinkPHP and Other PHP Frameworks based SwiftMailer

361.9k1](/packages/cattong-think-mailer)[aimeos/ai-swiftmailer

SwiftMailer adapter for Aimeos web shops and e-commerce solutions

20168.3k5](/packages/aimeos-ai-swiftmailer)[goetas/to-swift-mime-parser

Parse a generic mail stream, and convert it to a SwiftMailer Message

1244.4k2](/packages/goetas-to-swift-mime-parser)[andrewdyer/slim3-mailer

Email support for the Slim Framework using Twig and Swift Mailer.

1032.7k](/packages/andrewdyer-slim3-mailer)

PHPackages © 2026

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