README

此存储库是原始版本的分支，重新添加了一些由于被认为是“冗余”而被移除的PHPDoc。这导致在某些IDE中出现问题，为了完整性，在此分支中重新添加了。CI已重命名为使用我们组织的命名空间/此存储库，但为了兼容性，类仍然保留在原始命名空间中。一些CI服务可能没有实现。

IMAP库

PHP 7.2+库，用于通过IMAP读取和处理电子邮件。

此库需要安装IMAP、iconv和Multibyte String扩展。

功能请求

安装

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

$ composer require jocoon/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。如果您需要这些不受支持的搜索条件，则需要手动修补最新版本（当时此提交的2011年7月23日的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 服务器世界的异质性和为这种微小的收益带来的高复杂性负担，我们选择了后者。

模拟库

通过每个 API 存在的接口提供可模拟性。查看 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

jocoon / imap

维护者

详细信息