Email 類 · CodeIgniter 3.0.4 中文閱讀手冊

# Email 類 CodeIgniter 擁有強大的 Email 類支持以下特性： * 多協議：Mail、Sendmail 和 SMTP * SMTP 協議支持 TLS 和 SSL 加密 * 多個收件人 * 抄送（CC）和密送（BCC） * HTML 格式郵件或純文本郵件 * 附件 * 自動換行 * 優先級 * 密送批處理模式（BCC Batch Mode），大郵件列表將被分成小批次密送 * Email 調試工具 # 使用 Email 類 # 發送 Email 發送郵件不僅很簡單，而且你可以通過參數或通過配置文件設置發送郵件的不同選項。下面是個簡單的例子，用于演示如何發送郵件。注意：這個例子假設你是在某個控制器里面發送郵件。 ~~~ $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 參數有 21 種不同的參數可以用來對你發送的郵件進行配置。你可以像下面這樣手工設置它們，或者通過配置文件自動加載，見下文：通過向郵件初始化函數傳遞一個包含參數的數組來設置參數，下面是個如何設置參數的例子: ~~~ $config['protocol'] = 'sendmail'; $config['mailpath'] = '/usr/sbin/sendmail'; $config['charset'] = 'iso-8859-1'; $config['wordwrap'] = TRUE; $this->email->initialize($config); ~~~ **注解** 如果你不設置，大多數參數將使用默認值。 # 在配置文件中設置 Email 參數如果你不喜歡使用上面的方法來設置參數，你可以將它們放到配置文件中。你只需要簡單的創建一個新文件 email.php ，將 $config 數組放到該文件，然后保存到 config/email.php ，這樣它將會自動被加載。如果你使用配置文件的方式來設置參數，你就不需要使用 $this->email->initialize() 方法了。 # Email 參數下表為發送郵件時所有可用的參數。 | 參數 | 默認值 | 選項 | 描述 | | --- | --- | --- | --- | | useragent | CodeIgniter | None | 用戶代理（user agent）| | protocol | mail | mail, sendmail, or smtp | 郵件發送協議| | mailpath | /usr/sbin/sendmail | None | 服務器上 Sendmail 的實際路徑| | smtp_host |No Default | None | SMTP 服務器地址 | | smtp_user | No Default | None | SMTP 用戶名| | smtp_pass | No Default | None | SMTP 密碼 | | smtp_port | 25 |None | SMTP 端口| | smtp_timeout | 5 |None | SMTP 超時時間（單位：秒）| | smtp_keepalive | FALSE | TRUE or FALSE (boolean) | 是否啟用 SMTP 持久連接| | smtp_crypto | No Default | tls or ssl | SMTP 加密方式| | wordwrap | TRUE | TRUE or FALSE (boolean) | 是否啟用自動換行 | | wrapchars | 76 | | 自動換行時每行的最大字符數 | | mailtype | text| text or html | 郵件類型。如果發送的是 HTML 郵件，必須是一個完整的網頁，確保網頁中沒有使用相對路徑的鏈接和圖片地址，它們在郵件中不能正確顯示。 | | charset | $config['charset'] | | 字符集（utf-8, iso-8859-1 等） | | validate | FALSE | TRUE or FALSE (boolean) | 是否驗證郵件地址 | | priority |3 |1, 2, 3, 4, 5 | Email 優先級（1 = 最高. 5 = 最低. 3 = 正常） | |crlf | \n | "\r\n" or "\n" or "\r" | 換行符（使用 "rn" 以遵守 RFC 822）| | newline | \n | "\r\n" or "\n" or "\r" | 換行符（使用 "rn" 以遵守 RFC 822）| | bcc_batch_mode | FALSE | TRUE or FALSE (boolean) | 是否啟用密送批處理模式（BCC Batch Mode） | | bcc_batch_size | 200 | None | 使用密送批處理時每一批郵件的數量 | | dsn | FALSE | TRUE or FALSE (boolean) | 是否啟用服務器提示消息| # 取消自動換行如果你啟用了自動換行（推薦遵守 RFC 822），然后你的郵件中又有一個超長的鏈接，那么它也會被自動換行，會導致收件人無法點擊該鏈接。CodeIgniter 允許你禁用部分內容的自動換行，像下面這樣: ~~~ 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. ~~~ 在你不想自動換行的內容前后使用 {unwrap} {/unwrap} 包起來。 # 類參考 **class CI_Email** **from**($from[, $name = ''[, $return_path = NULL]]) 參數: * $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 設置發件人 email 地址和名稱: ~~~ $this->email->from('you@example.com', 'Your Name'); ~~~ 你還可以設置一個 Return-Path 用于重定向未收到的郵件: ~~~ $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com'); ~~~ **注解** 如果你使用的是 'smtp' 協議，不能使用 Return-Path 。 * * * * * **reply_to**($replyto[, $name = '']) 參數: * $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 函數中的值。例如: ~~~ $this->email->reply_to('you@example.com', 'Your Name'); ~~~ **to**($to) 參數: $to (mixed) -- Comma-delimited string or an array of e-mail addresses 返回: CI_Email instance (method chaining) 返回類型: CI_Email 設置收件人 email 地址，地址可以是單個、一個以逗號分隔的列表或是一個數組: ~~~ $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) 參數: $cc (mixed) -- Comma-delimited string or an array of e-mail addresses 返回: CI_Email instance (method chaining) 返回類型: CI_Email 設置抄送（CC）的 email 地址，和 "to" 方法一樣，地址可以是單個、一個以逗號分隔的列表或是一個數組。 * * * * * **bcc**($bcc[, $limit = '']) 參數: * $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" 方法一樣，地址可以是單個、一個以逗號分隔的列表或是一個數組。如果設置了 $limit 參數，將啟用批處理模式，批處理模式可以同時發送一批郵件，每一批不超過設置的 $limit 值。 * * * * * **subject**($subject) 參數: $subject (string) -- E-mail subject line 返回: CI_Email instance (method chaining) 返回類型: CI_Email 設置 email 主題: ~~~ $this->email->subject('This is my subject'); ~~~ * * * * * **message**($body) 參數: $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) 參數: $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'); ~~~ 如果你發送的是 HTML 格式的郵件，可以設置一個可選的正文部分。對于那些設置了不接受 HTML 格式的郵件的人來說，可以顯示一段備選的不包含 HTML 格式的文本。如果你沒有設置該參數，CodeIgniter 會自動從 HTML 格式郵件中刪掉 HTML 標簽。 * * * * * **set_header**($header, $value) 參數: * $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]) 參數: $clear_attachments (bool) -- Whether or not to clear attachments 返回: CI_Email instance (method chaining) 返回類型: CI_Email 將所有的 email 變量清空，當你在一個循環中發送郵件時，這個方法可以讓你在每次發郵件之前將變量重置。 ~~~ 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(); } ~~~ 如果將參數設置為 TRUE ，郵件的附件也會被清空。 ~~~ $this->email->clear(TRUE); ~~~ * * * * * **send**([$auto_clear = TRUE]) 參數: $auto_clear (bool) -- Whether to clear message data automatically 返回: TRUE on success, FALSE on failure 返回類型: bool 發送 email ，根據成功或失敗返回布爾值 TRUE 或 FALSE ，可以在條件語句中使用: ~~~ if ( ! $this->email->send()) { // Generate error } ~~~ 如果發送成功，該方法將會自動清除所有的參數。如果不想清除，可以將參數置為 FALSE ~~~ if ($this->email->send(FALSE)) { // Parameters won't be cleared } ~~~ **注解** 為了使用 print_debugger() 方法，你必須避免清空 email 的參數。 * * * * * **attach**($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]]) 參數: * $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 添加附件，第一個參數為文件的路徑。要添加多個附件，可以調用該方法多次。例如: ~~~ $this->email->attach('/path/to/photo1.jpg'); $this->email->attach('/path/to/photo2.jpg'); $this->email->attach('/path/to/photo3.jpg'); ~~~ 要讓附件使用默認的 Content-Disposition（默認為：attachment）將第二個參數留空，你也可以使用其他的 Content-Disposition ~~~ $this->email->attach('image.jpg', 'inline'); ~~~ 另外，你也可以使用 URL: ~~~ $this->email->attach('http://example.com/filename.pdf'); ~~~ 如果你想自定義文件名，可以使用第三個參數: ~~~ $this->email->attach('filename.pdf', 'attachment', 'report.pdf'); ~~~ 如果你想使用一段字符串來代替物理文件，你可以將第一個參數設置為該字符串，第三個參數設置為文件名，第四個參數設置為 MIME 類型: ~~~ $this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf'); ~~~ * * * * * **attachment_cid**($filename) 參數: $filename (string) -- Existing attachment filename 返回: Attachment Content-ID or FALSE if not found 返回類型: string 設置并返回一個附件的 Content-ID ，可以讓你將附件（圖片）內聯顯示到 HTML 正文中去。第一個參數必須是一個已經添加到附件中的文件名。 ~~~ $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 都必須重新創建，為了保證唯一性。 * * * * * **print_debugger**([$include = array('headers', 'subject', 'body')]) 參數: $include (array) -- Which parts of the message to print out 返回: Formatted debug data 返回類型: string 返回一個包含了所有的服務器信息、email 頭部信息、以及 email 信息的字符串，這些信息對調試很有用。你可以指定只返回消息的哪個部分，有效值有：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')); ~~~ **注解** 默認情況，所有的數據都會被打印出來。