Email 类
CodeIgniter 强大的 Email 类支持以下功能:
多种协议:Mail、Sendmail 和 SMTP
SMTP 的 TLS 和 SSL 加密
多个收件人
抄送和密送
HTML 或纯文本电子邮件
附件
文字换行
优先级
BCC 批量模式,可将大型邮件列表拆分为多个小的 BCC 批次。
电子邮件调试工具
使用 Email 库
发送电子邮件
发送电子邮件不仅很简单,而且你可以即时配置或在 app/Config/Email.php 文件中设置首选项。
下面是一个基本示例,演示了如何发送电子邮件:
<?php
$email = service('email');
$email->setFrom('your@example.com', 'Your Name');
$email->setTo('someone@example.com');
$email->setCC('another@another-example.com');
$email->setBCC('them@their-example.com');
$email->setSubject('Email Test');
$email->setMessage('Testing the email class.');
$email->send();
设置电子邮件首选项
有 21 个不同的首选项可用于定制电子邮件消息的发送方式。你可以像这里描述的那样手动设置它们,也可以通过存储在配置文件中的首选项自动设置,如 电子邮件首选项 中所述:
通过传递数组设置电子邮件首选项
首选项是通过向电子邮件初始化方法传递首选项值数组来设置的。下面是一个如何设置一些首选项的示例:
<?php
$config['protocol'] = 'sendmail';
$config['mailPath'] = '/usr/sbin/sendmail';
$config['charset'] = 'iso-8859-1';
$config['wordWrap'] = true;
$email->initialize($config);
备注
如果你不设置它们,大多数首选项都有默认值。
在配置文件中设置电子邮件首选项
如果你不喜欢使用上述方法设置首选项,你可以将它们放入配置文件中。只需打开
app/Config/Email.php 文件,并在电子邮件属性中设置你的配置。然后保存文件,它将被自动使用。
如果你在配置文件中设置了首选项,将 不需要 使用 $email->initialize() 方法。
SMTP 协议的 SSL 与 TLS
为了在与 SMTP 服务器通信时保护用户名、密码和电子邮件内容,应该对通道使用加密。已经广泛部署了两种不同的标准,在尝试排除电子邮件发送问题时,了解这些差异很重要。
当提交电子邮件时,大多数 SMTP 服务器允许在端口 465 或 587 上连接。(原始端口 25 很少使用,因为许多 ISP 有屏蔽规则,而且通信完全是明文的)。
关键差异在于端口 465 要求从一开始就使用 TLS 按照 RFC 8314 来保护通信通道。而端口 587 上的连接允许明文连接,之后会使用 STARTTLS SMTP 命令升级通道以使用加密。
端口 465 上的连接是否支持升级可能由服务器决定,所以如果服务器不允许, STARTTLS SMTP 命令可能会失败。如果你将端口设置为 465,你应该尝试设置 SMTPCrypto 为空字符串（''）,因为通信从一开始就是用 TLS 保护的,不需要 STARTTLS。
如果你的配置要求你连接到端口 587,你最好将 SMTPCrypto 设置为 tls,因为这将在与 SMTP 服务器通信时实现 STARTTLS 命令,将明文通道切换为加密通道。初始通信将是明文的,并使用 STARTTLS 命令将通道升级为 TLS。
检查首选项
成功发送的最后使用的设置可以从实例属性 $archive 获取。这对于测试和调试很有帮助,以确定在 send() 调用时的实际值。
电子邮件首选项
以下是发送电子邮件时可以设置的所有首选项列表。
首选项 |
默认值 |
选项 |
描述 |
|---|---|---|---|
fromEmail |
在 “from” 标头中设置的电子邮件地址。 |
||
fromName |
在 “from” 标头中设置的名称。 |
||
userAgent |
CodeIgniter |
“user agent”。 |
|
protocol |
|
邮件发送协议。 |
|
mailPath |
/usr/sbin/sendmail |
Sendmail 的服务器路径。 |
|
SMTPHost |
SMTP 服务器主机名。 |
||
SMTPUser |
SMTP 用户名。 |
||
SMTPPass |
SMTP 密码。 |
||
SMTPPort |
25 |
SMTP 端口。（如果设置为 |
|
SMTPTimeout |
5 |
SMTP 超时时间（以秒为单位）。 |
|
SMTPKeepAlive |
false |
|
启用持久的 SMTP 连接。 |
SMTPCrypto |
tls |
空字符串（ |
SMTP 加密。将此设置为 |
wordWrap |
true |
|
启用自动换行。 |
wrapChars |
76 |
换行的字符数。 |
|
mailType |
text |
|
邮件类型。如果发送 HTML 邮件，必须将其作为完整的网页发送。 确保没有任何相对链接或相对图像路径，否则它们将无法工作。 |
charset |
UTF-8 |
字符集 ( |
|
validate |
true |
|
是否验证电子邮件地址。 |
priority |
3 |
1, 2, 3, 4, 5 |
邮件优先级。 |
CRLF |
\r\n |
|
换行符。（使用 |
newline |
\r\n |
|
换行符。（使用 |
BCCBatchMode |
false |
|
启用 BCC 批处理模式。 |
BCCBatchSize |
200 |
每个 BCC 批次中的电子邮件数量。 |
|
DSN |
false |
|
启用来自服务器的通知消息。 |
覆盖文字换行
如果你启用了文字换行(遵循 RFC 822 的推荐)并且电子邮件中有一个非常长的链接,该链接也可能被换行,导致收件人无法点击。 CodeIgniter 允许你在消息的一部分手动覆盖文字换行,如下所示:
换行显示正常的电子邮件文本。
{unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}
更多正常显示换行的文本。
将你不想换行的项放在: {unwrap} {/unwrap} 之间。
类参考
- class CodeIgniter\Email\Email
- setFrom($from[, $name = ''[, $returnPath = null]])
- 参数:
$from (
string) – “From” 电子邮件地址$name (
string) – “From” 显示名称$returnPath (
string) – 可选的电子邮件地址，用于重定向未送达的邮件
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置发送电子邮件的人的电子邮件地址和名称：
<?php $email->setFrom('you@example.com', 'Your Name');
你还可以设置 Return-Path，以帮助重定向未送达的邮件：
<?php $email->setFrom('you@example.com', 'Your Name', 'returned_emails@example.com');
备注
如果你将协议配置为 ‘smtp’，则不能使用 Return-Path。
- setReplyTo($replyto[, $name = ''])
- 参数:
$replyto (
string) – 回复的电子邮件地址$name (
string) – 回复电子邮件地址的显示名称
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置回复地址。如果未提供信息，则使用 setFrom 方法中的信息。示例：
<?php $email->setReplyTo('you@example.com', 'Your Name');
- setTo($to)
- 参数:
$to (
mixed) – 逗号分隔的字符串或电子邮件地址数组
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置收件人的电子邮件地址。可以是单个电子邮件、逗号分隔的列表或数组：
<?php $email->setTo('someone@example.com');
<?php $email->setTo('one@example.com, two@example.com, three@example.com');
<?php $email->setTo(['one@example.com', 'two@example.com', 'three@example.com']);
- setCC($cc)
- 参数:
$cc (
mixed) – 逗号分隔的字符串或电子邮件地址数组
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置 CC 电子邮件地址。就像 “to” 一样，可以是单个电子邮件、逗号分隔的列表或数组。
- setBCC($bcc[, $limit = ''])
- 参数:
$bcc (
mixed) – 逗号分隔的字符串或电子邮件地址数组$limit (
int) – 每批发送的最大电子邮件数量
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置 BCC 电子邮件地址。就像
setTo()方法一样，可以是单个电子邮件、逗号分隔的列表或数组。如果设置了
$limit，将启用“批处理模式”，这将按批次发送电子邮件，每批次不超过指定的$limit。
- setSubject($subject)
- 参数:
$subject (
string) – 电子邮件主题
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置电子邮件主题：
<?php $email->setSubject('This is my subject');
- setMessage($body)
- 参数:
$body (
string) – 电子邮件正文
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置电子邮件正文：
<?php $email->setMessage('This is my message');
- setAltMessage($str)
- 参数:
$str (
string) – 替代电子邮件正文
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置替代电子邮件正文：
<?php $email->setAltMessage('This is the alternative message');
这是一个可选的消息字符串，可以在你发送 HTML 格式的电子邮件时使用。它允许你指定一个没有 HTML 格式的替代消息，该消息将添加到头字符串中，以便那些不接受 HTML 电子邮件的人使用。如果你没有设置自己的消息，CodeIgniter 将从你的 HTML 电子邮件中提取消息并去除标签。
- setHeader($header, $value)
- 参数:
$header (
string) – 头名称$value (
string) – 头值
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
向电子邮件添加附加头：
<?php $email->setHeader('Header1', 'Value1'); $email->setHeader('Header2', 'Value2');
- clear($clearAttachments = false)
- 参数:
$clearAttachments (
bool) – 是否清除附件
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
将所有电子邮件变量初始化为空状态。此方法旨在用于在循环中运行电子邮件发送方法，允许在循环之间重置数据。
<?php foreach ($list as $name => $address) { $email->clear(); $email->setTo($address); $email->setFrom('your@example.com'); $email->setSubject('Here is your info ' . $name); $email->setMessage('Hi ' . $name . ' Here is the info you requested.'); $email->send(); }
如果将参数设置为 true，任何附件也将被清除：
<?php $email->clear(true);
- send($autoClear = true)
- 参数:
$autoClear (
bool) – 是否自动清除消息数据
- 返回:
成功时返回 true，失败时返回 false
- 返回类型:
bool
电子邮件发送方法。根据成功或失败返回布尔值 true 或 false，使其可以有条件地使用：
<?php if (! $email->send()) { // Generate error }
如果请求成功，此方法将自动清除所有参数。要停止此行为，请传递 false：
<?php if ($email->send(false)) { // Parameters won't be cleared }
备注
为了使用
printDebugger()方法，你需要避免清除电子邮件参数。备注
如果启用了
BCCBatchMode，并且收件人超过BCCBatchSize，此方法将始终返回布尔值true。
- attach($filename[, $disposition = ''[, $newname = null[, $mime = '']]])
- 参数:
$filename (
string) – 文件名$disposition (
string) – 附件的 ‘disposition’。大多数电子邮件客户端会根据此处使用的 MIME 规范自行决定。https://www.iana.org/assignments/cont-disp/cont-disp.xhtml$newname (
string) – 在电子邮件中使用的自定义文件名$mime (
string) – 要使用的 MIME 类型（对缓冲数据有用）
- 返回:
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
允许你发送附件。将文件路径/名称放在第一个参数中。对于多个附件，请多次使用该方法。例如：
<?php $email->attach('/path/to/photo1.jpg'); $email->attach('/path/to/photo2.jpg'); $email->attach('/path/to/photo3.jpg');
要使用默认的 disposition（附件），请将第二个参数留空，否则使用自定义 disposition：
<?php $email->attach('image.jpg', 'inline');
你还可以使用 URL：
<?php $email->attach('http://example.com/filename.pdf');
如果你想使用自定义文件名，可以使用第三个参数：
<?php $email->attach('filename.pdf', 'attachment', 'report.pdf');
如果你需要使用缓冲字符串而不是实际的物理文件，可以将第一个参数用作缓冲区，第三个参数用作文件名，第四个参数用作 MIME 类型：
<?php $email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');
- setAttachmentCID($filename)
- 参数:
$filename (
string) – 已存在的附件文件名
- 返回:
附件内容 ID 或未找到时返回 false
- 返回类型:
string
设置并返回附件的内容 ID，这使你能够将内嵌（图片）附件嵌入 HTML 中。第一个参数必须是已附加的文件名。
<?php $filename = '/img/photo1.jpg'; $email->attach($filename); foreach ($list as $address) { $email->setTo($address); $cid = $email->setAttachmentCID($filename); $email->setMessage('<img src="cid:' . $cid . '" alt="photo1">'); $email->send(); }
备注
每封电子邮件的内容 ID 必须重新创建以确保其唯一性。
- printDebugger($include = ['headers', 'subject', 'body'])
- 参数:
$include (
array) – 要打印的消息部分
- 返回:
格式化的调试数据
- 返回类型:
string
返回包含任何服务器消息、电子邮件头和电子邮件消息的字符串。对调试很有用。
你可以选择性地指定应打印消息的哪些部分。有效选项是：headers、subject、body。
示例：
<?php // You need to pass false while sending in order for the email data // to not be cleared - if that happens, printDebugger() would have // nothing to output. $email->send(false); // Will only print the email headers, excluding the message subject and body $email->printDebugger(['headers']);
备注
默认情况下，将打印所有原始数据。