电子邮件类
CodeIgniter 的强大电子邮件类支持以下功能
多种协议：Mail、Sendmail 和 SMTP
用于 SMTP 的 TLS 和 SSL 加密
多个收件人
抄送和密送
HTML 或纯文本电子邮件
附件
自动换行
优先级
密送批量模式，使大型电子邮件列表可以分成小的密送批次。
电子邮件调试工具
使用邮件库
发送邮件
发送邮件不仅简单，您还可以动态配置它，或者在 **app/Config/Email.php** 文件中设置您的首选项。
以下是一个演示如何发送邮件的基本示例
<?php
$email = \Config\Services::email();
$email->setFrom('[email protected]', 'Your Name');
$email->setTo('[email protected]');
$email->setCC('[email protected]');
$email->setBCC('[email protected]');
$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 属性中设置您的配置。然后保存文件，它将自动使用。如果您在配置文件中设置了首选项，则无需使用 $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() 调用时的实际值。
电子邮件偏好设置
以下是发送电子邮件时可以设置的所有首选项列表。
首选项 |
默认值 |
选项 |
描述 |
|---|---|---|---|
userAgent |
CodeIgniter |
无 |
“用户代理”。 |
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 |
|
是否验证电子邮件地址。 |
优先级 |
3 |
1, 2, 3, 4, 5 |
电子邮件优先级。 |
CRLF |
\n |
|
换行符。（使用 |
换行 |
\n |
|
换行符。（使用 |
BCCBatchMode |
false |
|
启用 BCC 批量模式。 |
BCCBatchSize |
200 |
无 |
每个 BCC 批次中的电子邮件数量。 |
DSN |
false |
|
启用服务器的通知消息。 |
覆盖单词换行
如果您启用了单词换行（建议符合 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 CodeIgniter\Email\Email
- setFrom($from[, $name = ''[, $returnPath = null]])
- 参数：
$from (
string) – “From” 电子邮件地址$name (
string) – “From” 显示名称$returnPath (
string) – 可选的电子邮件地址，用于将未送达的电子邮件重定向到该地址
- 返回值：
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置发送电子邮件的人的电子邮件地址和姓名
<?php $email->setFrom('[email protected]', 'Your Name');
您还可以设置 Return-Path，以帮助重定向未送达的邮件
<?php $email->setFrom('[email protected]', 'Your Name', '[email protected]');
注意
如果您已将“smtp”配置为您的协议，则无法使用 Return-Path。
- setReplyTo($replyto[, $name = ''])
- 参数：
$replyto (
string) – 回复的电子邮件地址$name (
string) – 回复电子邮件地址的显示名称
- 返回值：
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置回复地址。如果未提供信息，则使用 setFrom 方法中的信息。示例
<?php $email->setReplyTo('[email protected]', 'Your Name');
- setTo($to)
- 参数：
$to (
mixed) – 逗号分隔的字符串或电子邮件地址数组
- 返回值：
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置收件人的电子邮件地址。可以是单个电子邮件、逗号分隔的列表或数组
<?php $email->setTo('[email protected]');
<?php $email->setTo('[email protected], [email protected], [email protected]');
<?php $email->setTo(['[email protected]', '[email protected]', '[email protected]']);
- setCC($cc)
- 参数：
$cc (
mixed) – 逗号分隔的字符串或电子邮件地址数组
- 返回值：
CodeIgniter\Email\Email 实例（方法链）
- 返回类型:
设置抄送电子邮件地址。就像“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('[email protected]'); $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) – 附件的“处置方式”。大多数电子邮件客户端会根据此处使用的 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');
要使用默认处置方式（附件），请将第二个参数留空，否则使用自定义处置方式
<?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
设置并返回附件的 Content-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(); }
注意
每封电子邮件的 Content-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']);
注意
默认情况下，将打印所有原始数据。