# 收發郵件
> 注意：本節正在開發中。
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）