README

这是一个 PHP 7.1+ 库，用于通过 IMAP 读取和处理电子邮件。

此库需要已安装 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);

您可以批量设置或清除邮箱邮件的任何标志（通过 UIDs）

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

$mailbox->clearFlag('\\Flagged', '1,3');

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

邮件

从邮箱中检索邮件并迭代它们

$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。如果您需要这些不受支持的搜索条件，则需要手动修补最新版本（在此次提交时为 23-Jul-2011 的 imap-2007f）并在修补的 c-client 库上重新编译 PHP。

顺便说一下，大多数常用搜索条件都是可用和工作的，在 ./src/Search 中浏览它们。

参考

https://stackoverflow.com/questions/36356715/imap-search-unknown-search-criterion-or
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

读取消息正文会将消息标记为未读。如果您想将消息标记为已读

$message->markAsSeen();

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

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

将消息移动到另一个邮箱

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

删除消息

$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
    }
}

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

超时

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

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

由于 IMAP 服务器世界的异构性以及这种前述小收益的高复杂负担成本，我们选择了后者。

模拟库

接口提供的可模拟性保证了可模拟性。查看 MockabilityTest 以获取模拟工作流程的示例。

运行测试

此库在 Travis CI 上对本地 Dovecot 服务器进行了功能测试。

如果您有您自己的 IMAP（测试）账户，您可以通过提供您的 IMAP 凭证在本地运行测试

$ composer install
$ IMAP_SERVER_NAME="my.imap.server.com" IMAP_SERVER_PORT="60993" IMAP_USERNAME="johndoe" IMAP_PASSWORD="p4ssword" vendor/bin/phpunit

您还可以将 phpunit.xml.dist 文件复制到自定义的 phpunit.xml 文件中，并将这些环境变量放入其中

<?xml version="1.0" encoding="UTF-8"?>
<phpunit
    bootstrap="./vendor/autoload.php"
    colors="true"
    verbose="true"
>
    <testsuites>
        <testsuite name="ddeboer/imap">
            <directory>./tests/</directory>
        </testsuite>
    </testsuites>
    <filter>
        <whitelist>
            <directory suffix=".php">./src</directory>
        </whitelist>
    </filter>
    <php>
        <env name="IMAP_SERVER_NAME" value="my.imap.server.com" />
        <env name="IMAP_SERVER_PORT" value="60993" />
        <env name="IMAP_USERNAME" value="johndoe" />
        <env name="IMAP_PASSWORD" value="p4ssword" />
    </php>
</phpunit>

警告测试会在不删除的情况下创建新的邮箱。

使用 Docker 运行测试

如果您已安装 Docker，您可以使用以下命令在本地运行测试

$ docker-compose run tests

php-experts / imap

维护者

详细信息