README

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

此库需要PHP >= 8.1，并安装IMAP、iconv和Multibyte String扩展。

安装

安装IMAP库的推荐方法是使用Composer

$ composer require ddeboer/imap

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

用法

连接和验证

use Ddeboer\Imap\Server;

$server = new Server('imap.gmail.com');

// $connection is instance of \Ddeboer\Imap\Connection
$connection = $server->authenticate('my_username', 'my_password');

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

$server = new Server(
    $hostname, // required
    $port,     // defaults to '993'
    $flags,    // defaults to '/imap/ssl/validate-cert'
    $parameters
);

邮箱

从邮件服务器检索邮箱（也称为邮件文件夹）并遍历它们

$mailboxes = $connection->getMailboxes();

foreach ($mailboxes as $mailbox) {
    // Skip container-only mailboxes
    // @see https://secure.php.net/manual/en/function.imap-getmailboxes.php
    if ($mailbox->getAttributes() & \LATT_NOSELECT) {
        continue;
    }

    // $mailbox is instance of \Ddeboer\Imap\Mailbox
    printf('Mailbox "%s" has %s messages', $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 is instance of \Ddeboer\Imap\Message
}

将新消息（刚刚发送的）插入已发送邮箱并将其标记为已读

$mailbox = $connection->getMailbox('Sent');
$mailbox->addMessage($messageMIME, '\\Seen');

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

搜索消息

use Ddeboer\Imap\SearchExpression;
use Ddeboer\Imap\Search\Email\To;
use Ddeboer\Imap\Search\Text\Body;

$search = new SearchExpression();
$search->addCondition(new To('me@here.com'));
$search->addCondition(new Body('contents'));

$messages = $mailbox->getMessages($search);

警告 目前我们无法同时转义空格和双引号。目前只能正确转义空格。您可以使用Ddeboer\Imap\Search\RawExpression自己编写完整的搜索条件。

消息也可以按imap_sort函数排序

$today = new DateTimeImmutable();
$thirtyDaysAgo = $today->sub(new DateInterval('P30D'));

$messages = $mailbox->getMessages(
    new Ddeboer\Imap\Search\Date\Since($thirtyDaysAgo),
    \SORTDATE, // Sort criteria
    true // Descending order
);

未知搜索标准：OR

请注意，PHP imap库依赖于位于https://www.washington.edu/imap/的c-client库，该库不支持一些IMAP4搜索标准，如OR。如果您需要这些不受支持的搜索标准，您需要手动修补最新版本（在本次提交时的imap-2007f版本为2011年7月23日）并重新编译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();    // Message\EmailAddress
$message->getTo();      // array of Message\EmailAddress
$message->getDate();    // DateTimeImmutable
$message->isAnswered();
$message->isDeleted();
$message->isDraft();
$message->isSeen();

获取消息头为 \Ddeboer\Imap\Message\Headers 对象

$message->getHeaders();

获取消息体作为 HTML 或纯文本（仅第一部分）

$message->getBodyHtml();    // Content of text/html part, if present
$message->getBodyText();    // Content of text/plain part, if present

获取完整的消息体（所有部分）

$body = $message->getCompleteBodyHtml();    // Content of text/html part, if present
if ($body === null) { // If body is null, there are no HTML parts, so let's try getting the text body
    $body = $message->getCompleteBodyText();    // Content of text/plain part, if present
}

读取消息体会使消息保持未读状态。如果您想标记消息为已读

$message->markAsSeen();

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

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

将消息移动到另一个邮箱

$mailbox = $connection->getMailbox('another-mailbox');
$message->move($mailbox);

删除消息

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

消息附件

获取消息附件（内嵌和附加的）并遍历它们

$attachments = $message->getAttachments();

foreach ($attachments as $attachment) {
    // $attachment is instance of \Ddeboer\Imap\Message\Attachment
}

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

// getDecodedContent() decodes the attachment’s contents automatically:
file_put_contents(
    '/my/local/dir/' . $attachment->getFilename(),
    $attachment->getDecodedContent()
);

嵌入消息

检查附件是否为嵌入消息，并获取它

$attachments = $message->getAttachments();

foreach ($attachments as $attachment) {
    if ($attachment->isEmbeddedMessage()) {
        $embeddedMessage = $attachment->getEmbeddedMessage();
        // $embeddedMessage is instance of \Ddeboer\Imap\Message\EmbeddedMessage
    }
}

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

超时

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

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

鉴于 IMAP 服务器世界的异构性和这种小幅度收益所承担的高复杂性成本，我们选择了后者。

模拟库

接口提供了可模拟性。有关模拟工作流程的示例，请参阅 MockabilityTest。

贡献：在本地运行构建

运行构建需要 Docker。

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

然后可以使用简单的 make 触发本地构建。

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