CodeIgniter Email 類

Email 類

CodeIgniter 擁有強大的 Email 類支持以下特性：

• 多協(xié)議：Mail、Sendmail 和 SMTP
• SMTP 協(xié)議支持 TLS 和 SSL 加密
• 多個收件人
• 抄送（CC）和密送（BCC）
• HTML 格式郵件 或 純文本郵件
• 附件
• 自動換行
• 優(yōu)先級
• 密送批處理模式（BCC Batch Mode），大郵件列表將被分成小批次密送
• Email 調(diào)試工具

使用 Email 類

發(fā)送 Email

發(fā)送郵件不僅很簡單，而且你可以通過參數(shù)或通過配置文件設置發(fā)送郵件的不同選項。

下面是個簡單的例子，用于演示如何發(fā)送郵件。注意：這個例子假設你是在某個 控制器 里面發(fā)送郵件。

$this->load->library('email');

$this->email->from('your@example.com', 'Your Name');
$this->email->to('someone@example.com');
$this->email->cc('another@another-example.com');
$this->email->bcc('them@their-example.com');

$this->email->subject('Email Test');
$this->email->message('Testing the email class.');

$this->email->send();

設置 Email 參數(shù)

有 21 種不同的參數(shù)可以用來對你發(fā)送的郵件進行配置。你可以像下面這樣手工設置它們， 或者通過配置文件自動加載，見下文：

通過向郵件初始化函數(shù)傳遞一個包含參數(shù)的數(shù)組來設置參數(shù)，下面是個如何設置參數(shù)的例子:

$config['protocol'] = 'sendmail';
$config['mailpath'] = '/usr/sbin/sendmail';
$config['charset'] = 'iso-8859-1';
$config['wordwrap'] = TRUE;

$this->email->initialize($config);

注解

如果你不設置，大多數(shù)參數(shù)將使用默認值。

在配置文件中設置 Email 參數(shù)

如果你不喜歡使用上面的方法來設置參數(shù)，你可以將它們放到配置文件中。你只需要簡單的創(chuàng)建一個新文件 email.php ，將 $config 數(shù)組放到該文件，然后保存到 config/email.php ，這樣它將會自動被加載。 如果你使用配置文件的方式來設置參數(shù)，你就不需要使用 $this->email->initialize() 方法了。

Email 參數(shù)

下表為發(fā)送郵件時所有可用的參數(shù)。

取消自動換行

如果你啟用了自動換行（推薦遵守 RFC 822），然后你的郵件中又有一個超長的鏈接，那么它也會被自動換行， 會導致收件人無法點擊該鏈接。CodeIgniter 允許你禁用部分內(nèi)容的自動換行，像下面這樣:

The text of your email that
gets wrapped normally.

{unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}

More text that will be
wrapped normally.

在你不想自動換行的內(nèi)容前后使用 {unwrap} {/unwrap} 包起來。

類參考

classCI_Email

from($from[, $name = ''[, $return_path = NULL]])

參數(shù):

• $from (string) -- "From" e-mail address
• $name (string) -- "From" display name
• $return_path (string) -- Optional email address to redirect undelivered e-mail to

返回: CI_Email instance (method chaining)

返回類型: CI_Email

設置發(fā)件人 email 地址和名稱:

$this->email->from('you@example.com', 'Your Name');

你還可以設置一個 Return-Path 用于重定向未收到的郵件:

$this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com');

注解

如果你使用的是 'smtp' 協(xié)議，不能使用 Return-Path 。

reply_to($replyto[, $name = ''])

參數(shù):

• $replyto (string) -- E-mail address for replies
• $name (string) -- Display name for the reply-to e-mail address

返回: CI_Email instance (method chaining)

返回類型: CI_Email

設置郵件回復地址，如果沒有提供這個信息，將會使用 :meth:from 函數(shù)中的值。例如:

$this->email->reply_to('you@example.com', 'Your Name');

to($to)

參數(shù):

• $to (mixed) -- Comma-delimited string or an array of e-mail addresses

  返回: CI_Email instance (method chaining)

  返回類型: CI_Email

設置收件人 email 地址，地址可以是單個、一個以逗號分隔的列表或是一個數(shù)組:

$this->email->to('someone@example.com');

$this->email->to('one@example.com, two@example.com, three@example.com');

$this->email->to(
    array('one@example.com', 'two@example.com', 'three@example.com')
);

cc($cc)

參數(shù):

• $cc (mixed) -- Comma-delimited string or an array of e-mail addresses

  返回: CI_Email instance (method chaining)

  返回類型: CI_Email

設置抄送（CC）的 email 地址，和 "to" 方法一樣，地址可以是單個、一個以逗號分隔的列表或是一個數(shù)組。

bcc($bcc[, $limit = ''])

參數(shù):

• $bcc (mixed) -- Comma-delimited string or an array of e-mail addresses

• $limit (int) -- Maximum number of e-mails to send per batch

  返回: CI_Email instance (method chaining)

  返回類型: CI_Email

設置密送（BCC）的 email 地址，和 "to" 方法一樣，地址可以是單個、一個以逗號分隔的列表或是一個數(shù)組。

如果設置了 $limit 參數(shù)，將啟用批處理模式，批處理模式可以同時發(fā)送一批郵件，每一批不超過設置的 $limit 值。

subject($subject)

參數(shù):

• $subject (string) -- E-mail subject line

返回: CI_Email instance (method chaining)

返回類型: CI_Email

設置 email 主題:

$this->email->subject('This is my subject');

message($body)

參數(shù):

• $body (string) -- E-mail message body

  返回: CI_Email instance (method chaining)

  返回類型: CI_Email

設置 email 正文部分:

$this->email->message('This is my message');

set_alt_message($str)

參數(shù):

• $str (string) -- Alternative e-mail message body

返回: CI_Email instance (method chaining)

返回類型: CI_Email

設置可選的 email 正文部分:

$this->email->set_alt_message('This is the alternative message');

如果你發(fā)送的是 HTML 格式的郵件，可以設置一個可選的正文部分。對于那些設置了不接受 HTML 格式的郵件的人來說， 可以顯示一段備選的不包含 HTML 格式的文本。如果你沒有設置該參數(shù)，CodeIgniter 會自動從 HTML 格式郵件中刪掉 HTML 標簽。

set_header($header, $value)

參數(shù):

• $header (string) -- Header name

• $value (string) -- Header value

  返回: CI_Email instance (method chaining)

  返回類型: CI_Email

向 email 添加額外的頭:

$this->email->set_header('Header1', 'Value1');
$this->email->set_header('Header2', 'Value2');

clear([$clear_attachments = FALSE])

參數(shù):

• $clear_attachments (bool) -- Whether or not to clear attachments

  返回: CI_Email instance (method chaining)

返回類型: CI_Email

將所有的 email 變量清空，當你在一個循環(huán)中發(fā)送郵件時，這個方法可以讓你在每次發(fā)郵件之前將變量重置。

foreach ($list as $name => $address)
{
    $this->email->clear();

    $this->email->to($address);
    $this->email->from('your@example.com');
    $this->email->subject('Here is your info '.$name);
    $this->email->message('Hi '.$name.' Here is the info you requested.');
    $this->email->send();
}

如果將參數(shù)設置為 TRUE ，郵件的附件也會被清空。

$this->email->clear(TRUE);

send([$auto_clear = TRUE])

參數(shù):

• $auto_clear (bool) -- Whether to clear message data automatically

  返回: TRUE on success, FALSE on failure

  返回類型: bool

發(fā)送 email ，根據(jù)成功或失敗返回布爾值 TRUE 或 FALSE ，可以在條件語句中使用:

if ( ! $this->email->send())
{
    // Generate error
}

如果發(fā)送成功，該方法將會自動清除所有的參數(shù)。如果不想清除，可以將參數(shù)置為 FALSE

if ($this->email->send(FALSE))
{
    // Parameters won't be cleared
}

注解

為了使用 print_debugger() 方法，你必須避免清空 email 的參數(shù)。

attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])

參數(shù):

• $filename (string) -- File name
• $disposition (string) -- 'disposition' of the attachment. Most email clients make their own decision regardless of the MIME specification used here. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml
• $newname (string) -- Custom file name to use in the e-mail

• $mime (string) -- MIME type to use (useful for buffered data)

  返回: CI_Email instance (method chaining)

  返回類型: CI_Email

添加附件，第一個參數(shù)為文件的路徑。要添加多個附件，可以調(diào)用該方法多次。例如:

$this->email->attach('/path/to/photo1.jpg');
$this->email->attach('/path/to/photo2.jpg');
$this->email->attach('/path/to/photo3.jpg');

要讓附件使用默認的 Content-Disposition（默認為：attachment）將第二個參數(shù)留空， 你也可以使用其他的 Content-Disposition

$this->email->attach('image.jpg', 'inline');

另外，你也可以使用 URL:

$this->email->attach('http://example.com/filename.pdf');

如果你想自定義文件名，可以使用第三個參數(shù):

$this->email->attach('filename.pdf', 'attachment', 'report.pdf');

如果你想使用一段字符串來代替物理文件，你可以將第一個參數(shù)設置為該字符串，第三個參數(shù)設置為文件名， 第四個參數(shù)設置為 MIME 類型:

$this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');

attachment_cid($filename)

參數(shù):

• $filename (string) -- Existing attachment filename

  返回: Attachment Content-ID or FALSE if not found

  返回類型: string

設置并返回一個附件的 Content-ID ，可以讓你將附件（圖片）內(nèi)聯(lián)顯示到 HTML 正文中去。 第一個參數(shù)必須是一個已經(jīng)添加到附件中的文件名。

$filename = '/img/photo1.jpg';
$this->email->attach($filename);
foreach ($list as $address)
{
    $this->email->to($address);
    $cid = $this->email->attachment_cid($filename);
    $this->email->message('<img src='cid:". $cid ."' alt="photo1" />');
    $this->email->send();
}

注解

每個 email 的 Content-ID 都必須重新創(chuàng)建，為了保證唯一性。

print_debugger([$include = array('headers', 'subject', 'body')])

參數(shù):

• $include (array) -- Which parts of the message to print out

  返回: Formatted debug data

  返回類型: string

返回一個包含了所有的服務器信息、email 頭部信息、以及 email 信息的字符串。用于調(diào)試。

你可以指定只返回消息的哪個部分，有效值有：headers 、 subject 和 body 。

例如:

// You need to pass FALSE while sending in order for the email data
// to not be cleared - if that happens, print_debugger() would have
// nothing to output.
$this->email->send(FALSE);

// Will only print the email headers, excluding the message subject and body
$this->email->print_debugger(array('headers'));

注解

默認情況，所有的數(shù)據(jù)都會被打印出來。