[ Laravel 5.2 文檔 ] 服務 -- 郵件

1、簡介

Laravel基於 SwiftMailer庫提供了一套乾淨清爽的郵件API。Laravel為SMTP、Mailgun、Mandrill、Amazon SES、PHP 的 mail函數，以及 sendmail提供了驅動，從而允許你快速通過本地或雲端服務發送郵件。

郵件驅動預備知識

基於驅動的 API 如Mailgun 和 Mandrill 通常比 SMTP 伺服器更簡單、更快。所有的 API 驅動要求應用已經安裝 Guzzle HTTP 庫。你可以通過添加如下行到 composer.json檔案來安裝 Guzzle 到項目：

"guzzlehttp/guzzle": "~5.3|~6.0"

Mailgun驅動

要使用 Mailgun 驅動（Mailgun 前10000封郵件免費，後續收費），首先安裝 Guzzle，然後在設定檔 config/mail.php中設定 driver選項為 mailgun。接下來，驗證設定檔 config/services.php包含如下選項：

'mailgun' => [    'domain' => 'your-mailgun-domain',    'secret' => 'your-mailgun-key',],

Mandrill驅動

要使用 Mandrill 驅動（Mandrill不支援中國區使用者註冊，汗！），首先安裝 Guzzle，然後在設定檔 config/mail.php中設定 driver選項值為 mandrill。接下來，驗證設定檔 config/services.php包含如下選項：

'mandrill' => [    'secret' => 'your-mandrill-key',],

SES驅動

要使用 Amazon SES 驅動（收費），安裝 Amazon AWS 的 PHP SDK，你可以通過添加如下行到 composer.json檔案的 require部分來安裝該庫：

"aws/aws-sdk-php": "~3.0"

接下來，設定設定檔 config/mail.php中的 driver選項為 ses。然後，驗證設定檔 config/services.php包含如下選項：

'ses' => [    'key' => 'your-ses-key',    'secret' => 'your-ses-secret',    'region' => 'ses-region',  // e.g. us-east-1],

2、發送郵件

Laravel 允許你在視圖中儲存郵件資訊，例如，要組織你的電子郵件，可以在 resources/views目錄下建立 emails目錄。

要發送一條資訊，使用 Mail 門面上的 send方法。 send方法接收三個參數。第一個參數是包含郵件資訊的視圖名稱；第二個參數是你想要傳遞到該視圖的數組資料；第三個參數是接收訊息執行個體的閉包回調——允許你自訂收件者、主題以及郵件其他方面的資訊：

 $user], function ($m) use ($user) {            $m->from('hello@app.com', 'Your Application');$m->to($user->email, $user->name)->subject('Your Reminder!');        });    }}

由於我們在上例中傳遞一個包含 user鍵的數組，我們可以在郵件中使用如下方式顯示使用者名稱：

name; ?>

注意： $message變數總是被傳遞到郵件視圖，並允許嵌入附件，因此，你應該在視圖負載中避免傳入訊息變數。

構造訊息

正如前面所討論的，傳遞給 send方法的第三個參數是一個允許你指定郵件訊息本身多個選項的閉包。使用這個閉包可以指定訊息的其他屬性，例如抄送、群發，等等：

Mail::send('emails.welcome', $data, function ($message) {    $message->from('us@example.com', 'Laravel');    $message->to('foo@example.com')->cc('bar@example.com');});

下面試 $message訊息構建器執行個體上的可用方法：

$message->from($address, $name = null);$message->sender($address, $name = null);$message->to($address, $name = null);$message->cc($address, $name = null);$message->bcc($address, $name = null);$message->replyTo($address, $name = null);$message->subject($subject);$message->priority($level);$message->attach($pathToFile, array $options = []);// 從$data字串追加檔案...$message->attachData($data, $name, array $options = []);// 擷取底層SwiftMailer訊息執行個體...$message->getSwiftMessage();

注意：傳遞給 Mail::send閉包的訊息執行個體繼承自 SwiftMailer訊息類，該執行個體允許你調用該類上的任何方法來構建自己的電子郵件訊息。

純文字郵件

預設情況下，傳遞給 send方法的視圖假定包含HTML，然而，通過傳遞數組作為第一個參數到 send方法，你可以指定發送除HTML視圖之外的純文字視圖：

Mail::send(['html.view', 'text.view'], $data, $callback);

或者，如果你只需要發送純文字郵件，可以指定在數組中使用text鍵：

Mail::send(['text' => 'view'], $data, $callback);

原生字串郵件

如果你想要直接發送原生字串郵件你可以使用 raw方法：

Mail::raw('Text to e-mail', function ($message) {    //});

2.1 附件

要添加附件到郵件，使用傳遞給閉包的 $message對象上的 attach方法。該方法接收檔案的絕對路徑作為第一個參數：

Mail::send('emails.welcome', $data, function ($message) {    //    $message->attach($pathToFile);});

當添加檔案到訊息時，你還可以通過傳遞數組作為第二個參數到 attach方法來指定檔案顯示名和MIME類型：

$message->attach($pathToFile, ['as' => $display, 'mime' => $mime]);

2.2 內聯附件

在郵件視圖中嵌入一張圖片

嵌套內聯圖片到郵件中通常是很笨重的，然而，Laravel提供了一個便捷的方式附加圖片到郵件並擷取相應的CID，要嵌入內聯圖片，在郵件視圖中使用 $message變數上的 embed方法。記住，Laravel自動在所有郵件視圖中傳入 $message變數使其有效：

    Here is an image:    embed($pathToFile); ?>">

在郵件視圖中嵌入原生資料

如果你想要在郵件訊息中嵌入原生資料字串，可以使用 $message變數上的 embedData方法：

    Here is an image from raw data:    embedData($data, $name); ?>">

2.3 郵件隊列

郵件訊息佇列

發送郵件訊息可能會大幅度延長應用的回應時間，許多開發人員選擇將郵件發送放到隊列中再後台執行，Laravel中可以使用內建的統一隊列API來實現。要將郵件訊息放到隊列中，使用 Mail門面上的 queue方法：

Mail::queue('emails.welcome', $data, function ($message) {    //});

該方法自動將郵件任務推送到隊列中以便在後台發送。當然，你需要在使用該特性前配置隊列。

延遲訊息佇列

如果你想要延遲已經放到隊列中郵件的發送，可以使用 later方法。只需要傳遞你想要延遲發送的秒數作為第一個參數到該方法即可：

Mail::later(5, 'emails.welcome', $data, function ($message) {    //});

推入指定隊列

如果你想要將郵件訊息推送到指定隊列，可以使用 queueOn和 laterOn方法：

Mail::queueOn('queue-name', 'emails.welcome', $data, function ($message) {    //});Mail::laterOn('queue-name', 5, 'emails.welcome', $data, function ($message) {    //});

3、郵件&本地開發

開發發送郵件的應用時，你可能不想要真的發送郵件到有效電子郵件地址，而只是想要做下測試。Laravel提供了幾種方式“禁止”郵件的實際發送。

日誌驅動

一種解決方案是在本地開發時使用 log郵件驅動。該驅動將所有郵件資訊寫到記錄檔中以備查看，想要瞭解更多關於每個環境的應用配置資訊，查看配置文檔。

通用配置

Laravel提供的另一種解決方案是為架構發送的所有郵件設定通用收件者，這樣的話，所有應用產生的郵件將會被發送到指定地址，而不是實際發送郵件指定的地址。這可以通過在設定檔 config/mail.php中設定 to選項來實現：

'to' => [    'address' => 'dev@domain.com',    'name' => 'Dev Example'],

Mailtrap

最後，你可以使用 Mailtrap服務和 smtp驅動發送郵件資訊到“虛擬”郵箱，這種方法允許你在Mailtrap的訊息查看器中查看最終的郵件。

4、 事件

Laravel 會發送郵件前觸發一個事件，記住，這個事件是在郵件被發送時觸發，而不是推送到隊列時，你可以在 EventServiceProvider中註冊事件監聽器：

/** * The event listener mappings for the application. * * @var array */protected $listen = [    'Illuminate\Mail\Events\MessageSending' => [        'App\Listeners\LogSentMessage',    ],];

