# 收发邮件
> 注意：本节正在开发中。
Yii 支持组成和发送电子邮件。然而，该框架提供的只有内容组成功能和基本接口。实际的邮件发送机制可以通过扩展提供， 因为不同的项目可能需要不同的实现方式，它通常取决于外部服务和库。
大多数情况下你可以使用 [yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer) 官方扩展。
## 配置
邮件组件配置取决于你所使用的扩展。一般来说你的应用程序配置应如下：
~~~
return [
//....
'components' => [
'mailer' => [
'class' => 'yii\swiftmailer\Mailer',
],
],
];
~~~
## 基本用法
一旦 “mailer” 组件被配置，可以使用下面的代码来发送邮件：
~~~
Yii::$app->mailer->compose()
->setFrom('from@domain.com')
->setTo('to@domain.com')
->setSubject('Message subject')
->setTextBody('Plain text content')
->setHtmlBody('<b>HTML content</b>')
->send();
~~~
在上面的例子中所述的 `compose()` 方法创建了电子邮件消息，这是填充和发送的一个实例。 如果需要的话在这个过程中你可以用上更复杂的逻辑：
~~~
$message = Yii::$app->mailer->compose();
if (Yii::$app->user->isGuest) {
$message->setFrom('from@domain.com')
} else {
$message->setFrom(Yii::$app->user->identity->email)
}
$message->setTo(Yii::$app->params['adminEmail'])
->setSubject('Message subject')
->setTextBody('Plain text content')
->send();
~~~
> 注意：每个 “mailer” 的扩展也有两个主要类别：“Mailer” 和 “Message”。 “Mailer” 总是知道类名和具体的 “Message”。 不要试图直接实例 “Message” 对象 - 而是始终使用 `compose()` 方法。
你也可以一次发送几封邮件：
~~~
$messages = [];
foreach ($users as $user) {
$messages[] = Yii::$app->mailer->compose()
// ...
->setTo($user->email);
}
Yii::$app->mailer->sendMultiple($messages);
~~~
一些特定的扩展可能会受益于这种方法，使用单一的网络消息等。
## 撰写邮件内容
Yii 允许通过特殊的视图文件来撰写实际的邮件内容。默认情况下，这些文件应该位于 “@app/mail” 路径。
一个邮件视图内容的例子：
~~~
<?php
use yii\helpers\Html;
use yii\helpers\Url;
/* @var $this \yii\web\View view component instance */
/* @var $message \yii\mail\BaseMessage instance of newly created mail message */
?>
<h2>This message allows you to visit our site home page by one click</h2>
<?= Html::a('Go to home page', Url::home('http')) ?>
~~~
为了通过视图文件撰写正文可传递视图名称到 `compose()` 方法中：
~~~
Yii::$app->mailer->compose('home-link') // 渲染一个视图作为邮件内容
->setFrom('from@domain.com')
->setTo('to@domain.com')
->setSubject('Message subject')
->send();
~~~
你也可以在 `compose()` 方法中传递一些视图所需参数，这些参数可以在视图文件中使用：
~~~
Yii::$app->mailer->compose('greetings', [
'user' => Yii::$app->user->identity,
'advertisement' => $adContent,
]);
~~~
你可以指定不同的视图文件的 HTML 和纯文本邮件内容：
~~~
Yii::$app->mailer->compose([
'html' => 'contact-html',
'text' => 'contact-text',
]);
~~~
如果指定视图名称为纯字符串，它的渲染结果将被用来作为 HTML Body，同时纯文本正文将被删除所有 HTML 实体。
视图渲染结果可以被包裹进布局，可使用 yii\mail\BaseMailer::htmlLayout 和 yii\mail\BaseMailer::textLayout 来设置。 它的运行方式跟常规应用程序的布局是一样的。布局可用于设置邮件 CSS 样式或其他共享内容：
~~~
<?php
use yii\helpers\Html;
/* @var $this \yii\web\View view component instance */
/* @var $message \yii\mail\MessageInterface the message being composed */
/* @var $content string main view render result */
?>
<?php $this->beginPage() ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=<?= Yii::$app->charset ?>" />
<style type="text/css">
.heading {...}
.list {...}
.footer {...}
</style>
<?php $this->head() ?>
</head>
<body>
<?php $this->beginBody() ?>
<?= $content ?>
<div class="footer">With kind regards, <?= Yii::$app->name ?> team</div>
<?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>
~~~
## 文件附件
你可以使用 `attach()` 和 `attachContent()` 方法来添加附件的信息：
~~~
$message = Yii::$app->mailer->compose();
// 附件来自本地文件
$message->attach('/path/to/source/file.pdf');
// 动态创建一个文件附件
$message->attachContent('Attachment content', ['fileName' => 'attach.txt', 'contentType' => 'text/plain']);
~~~
## 嵌入图片
你可以使用 `embed()` 方法将图片插入到邮件内容。此方法返回会图片 ID ，这将用在 "img" 标签中。 当通过视图文件来写信时，这种方法易于使用：
~~~
Yii::$app->mailer->compose('embed-email', ['imageFileName' => '/path/to/image.jpg'])
// ...
->send();
~~~
然后在该视图文件中，你可以使用下面的代码：
~~~
<img src="/docs/guide/2.0/<?= $message->embed($imageFileName); ?>">
~~~
## 测试和调试
开发人员常常要检查一下，有什么电子邮件是由应用程序发送的，他们的内容是什么等。这可通过`yii\mail\BaseMailer::useFileTransport` 来检查。 如果开启这个选项，会把邮件信息保存在本地文件而不是发送它们。这些文件保存在 `yii\mail\BaseMailer::fileTransportPath` 中，默认在 '@runtime/mail' 。
> 提示: 你可以保存这些信息到本地文件或者把它们发送出去，但不能同时两者都做。
邮件信息文件可以在一个普通的文本编辑器中打开，这样你就可以浏览实际的邮件标题，内容等。这种机制可以用来调试应用程序或运行单元测试。
> 提示: 该邮件信息文件是会被 `\yii\mail\MessageInterface::toString()` 转成字符串保存的，它依赖于实际在应用程序中使用的邮件扩展。
## 创建自己的邮件解决方案
为了创建你自己的邮件解决方案，你需要创建两个类，一个用于 “Mailer”，另一个用于 “Message”。 你可以使用`yii\mail\BaseMailer` 和 `yii\mail\BaseMessage` 作为基类。这些类已经实现了基本的逻辑，这在本指南中有介绍。 然而，它们的使用不是必须的，它实现了 `yii\mail\MailerInterface` 和 `yii\mail\MessageInterface` 接口。 然后，你需要实现所有 abstract 方法来构建解决方案。
- 介绍（Introduction）
- 关于 Yii（About Yii）
- 从 Yii 1.1 升级（Upgrading from Version 1.1）
- 入门（Getting Started）
- 安装 Yii（Installing Yii）
- 运行应用（Running Applications）
- 第一次问候（Saying Hello）
- 使用 Forms（Working with Forms）
- 玩转 Databases（Working with Databases）
- 用 Gii 生成代码（Generating Code with Gii）
- 更上一层楼（Looking Ahead）
- 应用结构（Application Structure）
- 结构概述（Overview）
- 入口脚本（Entry Scripts）
- 应用（Applications）
- 应用组件（Application Components）
- 控制器（Controllers）
- 模型（Models）
- 视图（Views）
- 模块（Modules）
- 过滤器（Filters）
- 小部件（Widgets）
- 前端资源（Assets）
- 扩展（Extensions）
- 请求处理（Handling Requests）
- 运行概述（Overview）
- 引导（Bootstrapping）
- 路由引导与创建 URL（Routing and URL Creation）
- 请求（Requests）
- 响应（Responses）
- Sessions and Cookies
- 错误处理（Handling Errors）
- 日志（Logging）
- 关键概念（Key Concepts）
- 组件（Components）
- 属性（Properties）
- 事件（Events）
- 行为（Behaviors）
- 配置（Configurations）
- 别名（Aliases）
- 类自动加载（Class Autoloading）
- 服务定位器（Service Locator）
- 依赖注入容器（Dependency Injection Container）
- 配合数据库工作（Working with Databases）
- 数据库访问（Data Access Objects）: 数据库连接、基本查询、事务和模式操作
- 查询生成器（Query Builder）: 使用简单抽象层查询数据库
- 活动记录（Active Record）: 活动记录对象关系映射（ORM），检索和操作记录、定义关联关系
- 数据库迁移（Migrations）: 在团体开发中对你的数据库使用版本控制
- Sphinx
- Redis
- MongoDB
- ElasticSearch
- 接收用户数据（Getting Data from Users）
- 创建表单（Creating Forms）
- 输入验证（Validating Input）
- 文件上传（Uploading Files）
- 收集列表输入（Collecting Tabular Input）
- 多模型同时输入（Getting Data for Multiple Models）
- 显示数据（Displaying Data）
- 格式化输出数据（Data Formatting）
- 分页（Pagination）
- 排序（Sorting）
- 数据提供器（Data Providers）
- 数据小部件（Data Widgets）
- 操作客户端脚本（Working with Client Scripts）
- 主题（Theming）
- 安全（Security）
- 认证（Authentication）
- 授权（Authorization）
- 处理密码（Working with Passwords）
- 客户端认证（Auth Clients）
- 安全领域的最佳实践（Best Practices）
- 缓存（Caching）
- 概述（Overview）
- 数据缓存（Data Caching）
- 片段缓存（Fragment Caching）
- 分页缓存（Page Caching）
- HTTP 缓存（HTTP Caching）
- RESTful Web 服务
- 快速入门（Quick Start）
- 资源（Resources）
- 控制器（Controllers）
- 路由（Routing）
- 格式化响应（Response Formatting）
- 授权验证（Authentication）
- 速率限制（Rate Limiting）
- 版本化（Versioning）
- 错误处理（Error Handling）
- 开发工具（Development Tools）
- 调试工具栏和调试器（Debug Toolbar and Debugger）
- 使用 Gii 生成代码（Generating Code using Gii）
- TBD 生成 API 文档（Generating API Documentation）
- 测试（Testing）
- 概述（Overview）
- 搭建测试环境（Testing environment setup）
- 单元测试（Unit Tests）
- 功能测试（Functional Tests）
- 验收测试（Acceptance Tests）
- 测试夹具（Fixtures）
- 高级专题（Special Topics）
- 高级应用模版（Advanced Project Template）
- 从头构建自定义模版（Building Application from Scratch）
- 控制台命令（Console Commands）
- 核心验证器（Core Validators）
- 国际化（Internationalization）
- 收发邮件（Mailing）
- 性能优化（Performance Tuning）
- 共享主机环境（Shared Hosting Environment）
- 模板引擎（Template Engines）
- 集成第三方代码（Working with Third-Party Code）
- 小部件（Widgets）
- Bootstrap 小部件（Bootstrap Widgets）
- jQuery UI 小部件（jQuery UI Widgets）
- 助手类（Helpers）
- 助手一览（Overview）
- Array 助手（ArrayHelper）
- Html 助手（Html）
- Url 助手（Url）