imap

PHP IMAP 库

一个 PHP IMAP 库，用于通过 IMAP 协议读取和处理电子邮件，采用强大的面向对象架构构建。

该库需要 PHP >= 8.3，并安装 IMAP、inov 和多字节字符串扩展。

安装

安装 IMAP 库的推荐方法是通过 Composer：

 $ 作曲家需要 ddeboer/imap

此命令要求您全局安装 Composer，如 Composer 文档的安装章节中所述。

用法

连接并验证

use DdeboerImapServer;$server = new Server('imap.gmail.com');// $connection 是 DdeboerImapConnection 的实例$connection = $server->authenticate('my_username', 'my_password');

您可以指定服务器的端口、标志和参数：

 $server = new Server($hostname, // 必需的$port, // 默认为 '993'$flags, // 默认为 '/imap/ssl/validate-cert'$parameters);

邮箱

从邮件服务器检索邮箱（也称为邮件文件夹）并迭代它们：

 $mailboxes = $connection->getMailboxes();foreach ($mailboxes as $mailbox) {// 跳过仅容器邮箱// @see https://secure.php.net/manual/en/function.imap-getmailboxes .phpif ($mailbox->getAttributes() & LATT_NOSELECT) {继续;
    }// $mailbox 是 DdeboerImapMailboxprintf('邮箱“%s”有 %s 条邮件', $mailbox->getName(), $mailbox->count()); 的实例
}

或者检索特定邮箱：

 $mailbox = $connection->getMailbox('INBOX');

删除邮箱：

 $connection->deleteMailbox($mailbox);

您可以批量设置或清除邮箱消息的任何标志（通过 UID）：

 $mailbox->setFlag('Seen Flagged', ['1:5', '7', '9']);$mailbox->setFlag('Seen', '1,3,5,6: 8');$mailbox->clearFlag('Flagged', '1,3');

警告在批量修改标志的情况下，您必须检索新的消息实例以刷新单个消息标志。

留言

从邮箱检索消息（电子邮件）并迭代它们：

 $messages = $mailbox->getMessages();foreach ($messages as $message) {// $message 是 DdeboerImapMessage 的实例}

要将新邮件（刚刚发送的邮件）插入“已发送”邮箱并将其标记为“已发送”：

 $mailbox = $connection->getMailbox('已发送');$mailbox->addMessage($messageMIME, 'Seen');

请注意，消息应该是 MIME 格式的字符串（如 RFC2045 中所述）。

搜索消息

使用 DdeboerImapSearchExpression;使用 DdeboerImapSearchEmailTo;使用 DdeboerImapSearchTextBody;$search = new SearchExpression();$search->addCondition(new To('[email protected]'));$search->addCondition(new Body('contents')) ;$messages = $mailbox->getMessages($search);

警告我们目前无法同时转义空格和双引号。当前仅正确转义空格。您可以使用DdeboerImapSearchRawExpression自行编写完整的搜索条件。

还可以按照 imap_sort 函数排序检索消息：

 $today = new DateTimeImmutable();$thirtyDaysAgo = $today->sub(new DateInterval('P30D'));$messages = $mailbox->getMessages(new DdeboerImapSearchDateSince($thirtyDaysAgo),SORTDATE, // 排序条件true //降序排列）；

未知搜索条件：OR

请注意，PHP imap 库依赖于 https://www.washington.edu/imap/ 上提供的c-client库，该库不完全支持某些 IMAP4 搜索条件，例如OR 。如果您想要那些不受支持的标准，则需要手动修补最新版本（本次提交时为 2011 年 7 月 23 日的imap-2007f ），并将 PHP 重新编译到已修补的c-client端库上。

顺便说一下，大多数常见的搜索条件都可用且有效，请在./src/Search中浏览它们。

参考：

1. https://stackoverflow.com/questions/36356715/imap-search-unknown-search-criterion-or

2. imap-2007f.tar.gz： ./src/c-client/mail.c和./docs/internal.txt

消息属性和操作

以 <...> 形式获取消息编号和唯一消息 id：

 $message->getNumber();$message->getId();

获取其他消息属性：

 $message->getSubject();$message->getFrom();    // MessageEmailAddress$message->getTo();      // MessageEmailAddress$message->getDate() 数组；    // DateTimeImmutable$message->isAnswered();$message->isDeleted();$message->isDraft();$message->isSeen();

获取 DdeboerImapMessageHeaders 对象形式的消息头：

 $message->getHeaders();

获取 HTML 或纯文本形式的消息正文（仅第一部分）：

 $message->getBodyHtml();    // text/html 部分的内容，如果存在$message->getBodyText();    // 文本/纯文本部分的内容（如果存在）

获取完整的身体（所有部分）：

 $body = $message->getCompleteBodyHtml();    // text/html 部分的内容 if presentif ($body === null) { // 如果 body 为 null，则没有 HTML 部分，所以让我们尝试获取文本 body$body = $message->getCompleteBodyText() ;    // 文本/纯文本部分的内容（如果存在）}

读取消息正文会使消息保持不可见状态。如果您想将消息标记为已查看：

 $message->markAsSeen();

或者您可以设置或清除任何标志：

 $message->setFlag('Seen Flagged');$message->clearFlag('Flagged');

将邮件移至另一个邮箱：

 $mailbox = $connection->getMailbox('另一个邮箱');$message->move($mailbox);

删除消息：

 $邮箱->getMessage(1)->delete();$邮箱->getMessage(2)->delete();$connection->expunge();

消息附件

获取消息附件（内联和附加）并迭代它们：

 $attachments = $message->getAttachments();foreach ($attachments as $attachment) {// $attachment 是 DdeboerImapMessageAttachment 的实例}

将消息附件下载到本地文件：

 // getDecodedContent() 自动解码附件内容:file_put_contents('/my/local/dir/' . $attachment->getFilename(),$attachment->getDecodedContent()
）；

嵌入消息

检查附件是否嵌入消息并获取：

 $attachments = $message->getAttachments();foreach ($attachments as $attachment) {if ($attachment->isEmbeddedMessage()) {$embeddedMessage = $attachment->getEmbeddedMessage();// $embeddedMessage 是 DdeboerImapMessageEmbeddedMessage 的实例}
}

除了标志和复制、移动或删除等操作之外，EmbeddedMessage 具有与普通消息相同的 API。

超时

IMAP扩展提供了imap_timeout函数来调整各种操作的超时秒数。

然而，扩展的实现并不将功能链接到特定的上下文或连接，而是全局的。因此，为了不影响该库之外的功能，我们必须选择是将每个imap_*调用包装在可选的用户提供的超时周围，还是将此任务留给用户。

由于 IMAP 服务器的异构世界以及前者的一点点收益所带来的高复杂性负担成本，我们选择了后者。

模拟图书馆

可模拟性是由每个 API 的接口授予的。深入研究 MockabilityTest 以获取模拟工作流程的示例。

贡献：在本地运行构建

需要 Docker 才能在您的计算机上运行构建。

您需要运行的第一个命令是make start-imap-server ，它在本地启动 IMAP 服务器。

然后可以通过裸make触发本地构建。

完成开发后，使用make stop-imap-server停止本地 IMAP 服务器。