README

ImapMailManager 提供了方便的 OOP 类，用于在 PHP 中通过 imap 管理收到的电子邮件时执行常见任务。

注意： 此包目前处于 beta 版本。预计在接下来的几周内将发布一个完全稳定的版本。

功能

提供搜索 imap 邮箱的方便方法
自动检测、解码和编码电子邮件消息和附件。
将消息编码为 UTF-8 以获得最佳显示效果。
提供简单的下载附件和嵌入式图像的方法。
通过配置文件进行配置，而不是硬编码用户名和密码信息。
将 php 的原生 imap 响应转换为简单的值对象，以便轻松访问。

入门指南

ImapMailManager 提供了两个主要的服务类，用于在邮箱（搜索邮箱中的消息、文件夹等）上执行任务，以及在消息本身（下载附件）上执行任务。已提供方便的工厂来帮助创建所需的对象。

配置

连接到邮箱的最简单方法是通过提供配置文件中的设置。

return [
    'server' => 'imap.example.com',
    'username' => 'USERNAME',
    'password' => 'PASSWORD',
    'port' => 993,
    'ssl' => true,
    'validate_cert' => true,
];

别名

别名提供了一种方便的方式来引用邮箱文件夹，例如，如果您使用不同的 config 文件连接到多个邮箱，您可以在配置文件中提供文件夹别名。这意味着您可以避免硬编码文件夹名称，并使用 if 语句检测您连接到的邮箱以获取正确的文件夹名称。要创建别名，您只需在您的 config 文件中添加一个 aliases 数组，然后可以将这些别名传递给请求文件夹名称的方法，例如 moveToFolder('spam')

return [
    'server' => 'imap.example.com',
    'username' => 'USERNAME',
    'password' => 'PASSWORD',
    'port' => 993,
    'ssl' => true,
    'validate_cert' => true,
    'aliases' => [
      'trash' => 'INBOX.Trash',
      'spam' => 'INBOX.Spam'
    ]
];

添加 trash 别名是个好主意，因为这个别名是 moveToTrash() 和 emptyTrash() 方法自动使用的别名。否则，您需要将文件夹名称作为参数传递：例如 moveToTrash('INBOX.Trash')

生成配置文件

ImapMailManager 提供了一个名为 createImapConfig.php 的配置生成器，可以从 composer 的 vendor/bin 文件夹中运行，它将在脚本运行的文件夹中创建 'imap_config/config.php'。

或者，您可以直接将 config.php 中的代码复制并粘贴到您自己的配置文件中。

默认情况下，ImapMailManager 在 imap_config/config.php 中查找您的配置文件，您可以通过直接将配置位置传递到相关类的构造函数或工厂方法来更改此设置。（见文档）

列出电子邮件

以下示例使用提供的工厂构建来自您的收件箱的消息集合。有关如何使用构造函数达到相同结果的信息，请参阅下面的 使用构造函数创建 Imap 而不使用配置。

// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create('INBOX');
// Create a new service
$mailboxService = new ImapMailboxService($imap);

// Get all messages in the folder (this returns an array of message numbers)
$all = $mailboxService->getAllMessages();

// Create a collection of Message objects
$messages = ImapMessagesCollectionFactory::create($all);

现在您可以通过循环消息来显示消息主题列表

if(count($messages)){
    foreach($messages as $message){
      echo $message->getSubject().'<br>';
    }
}

显示消息

$messageNum = $_REQUEST['messageNum'];

// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create('INBOX');

// Get the current message
$message = ImapMessageFactory::create($messageNum, $imap);
// Create a new service
$messageService = new ImapMessageService($message, $imap);

echo $message->getSubject().'<br />';
echo $message->getHtmlBody();

您应该查看 ImapMessage 类的文档，以了解可用于检索消息信息的方法。您还可以查看 examples\showMessage.php，它提供了一个显示消息的更完整的示例。

处理附件

ImapMailManager 通过提取附件信息、解码并将附件保存到相关文件夹，消除了下载附件的所有麻烦。

下载所有附件

要下载消息的所有附件，您只需要以下内容

$messageNum = $_REQUEST['messageNum'];

// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create('INBOX');

// Get the current message
$message = ImapMessageFactory::create($messageNum, $imap);
$message->downloadAttachments('path/to/download/to');

下载单个附件

您通常会想下载单个附件，为此 ImapMailManager 提供了一些便捷方法：downloadAttachmentByFilename()、downloadAttachmentByPart() 和 downloadAttachment()。您可以使用返回消息上的 getAttachments() 方法检索一个包含 Attachment 对象的集合，这些对象提供了 getFilename() 和 getPart() 方法

按文件名下载附件

// Filename passed from the previous page, this can be retrieved using the `getFilename()` method on the Attachment object.
$filename = $_REQUEST['filename'];
// The folder for the message, this can be retreived using `getFolder()` on the Mailbox object (see `examples\exmple.php`)
$folder = $_REQUEST['folder'];

// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create($folder);

// Get the current message
$message = ImapMessageFactory::create($messageNum, $imap);
// Create a new service
$messageService = new ImapMessageService($message, $imap);

$messageService->downloadAttachmentByFilename($filename, 'attachment/download/path');

下载嵌入式图像

某些电子邮件直接将图像嵌入其中，默认情况下 ImapMailManager 不会下载这些图像，因此它们不会显示。如果您想下载并显示嵌入式图像，只需在显示消息时调用 downloadEmbeddedImages() 方法即可

$messageNum = $_REQUEST['messageNum'];
// The folder for the message, this can be retreived using `getFolder()` on the Mailbox object (see `examples\exmple.php`)
$folder = $_REQUEST['folder'];
// Creates the relevant imap classes to be passed to a service
$imap = ImapFactory::create(folder);

// Get the current message
$message = ImapMessageFactory::create($messageNum, $imap);
// Create a new service
$messageService = new ImapMessageService($message, $imap);
// Download any embedded images, without this embedded images will not display.
$messageService->downloadEmbeddedImages('path/to/download/to');

// Display Message with embedded images
$message->getHtmlBody()

为了避免覆盖嵌入式图像，它们将被保存到 your/path/folderName/messageNumber。

注意： 只有当嵌入式图像在下载位置不存在时，才会下载它们，它们不会在每次打开消息时都下载。

使用构造函数和没有配置创建 Imap

虽然工厂方法提供了一种方便的方式来创建一个传递给服务或工厂的 Imap 类，但它隐藏了很多正在进行的事情。为了更好地理解 ImapMailManager 的工作方式，以下显示了如何直接构造 MailboxService 对象

// We don't have a config file, so lets create the mailbox directly
$mailbox = new Mailbox('imap.example.com', 'username', 'password', 'INBOX');
// Now lets connect to the mailbox
$imapConnection = new ImapConnection($mailbox);
// Now create an ImapHandler object, which is used to perform various tasks on the mailbox
$imap = new ImapHandler($imapConnection);
// Finally create the service
$mailboxService = new MailboxService($imap);

注意： 直接创建消息对象相当复杂，因此仍然应使用工厂来创建消息对象和集合。

运行示例

这些示例需要您在 examples/imap_config/config.php 中提供自己的配置文件，您可以通过使用在 vendor\bin 中找到的生成器来完成此操作，或者简单地手动创建一个，您可以在该项目的根目录中找到基本配置文件 config.php。

然后，您需要更改 config.php 文件中的设置以匹配您的电子邮件账户，然后您应该能够运行示例。

文档

使用 ImapMailManager 可以完成比这些示例更多的事情。您可以在提供的 HTML 中的 docs 文件夹中找到方法列表和描述。我希望很快就能将这些在线。

注意事项

关于集合的说明

ImapMailMainager 返回集合作为 Collection 对象。您可以像对待正常的 php 数组一样对待它们，因此您仍然可以使用 count 和 foreach 在它们上，以及通过它们的数组索引 MessageCollection[0] 访问它们。

关于 JSON 编码的说明

所有值对象和集合都设计为易于 JSON 编码（并提供一个 toJson() 方法），但是，您可能会发现对象的一些部分在 JSON 编码时没有被包括，这些通常是 php 的 imap 函数的原始响应，如果它们不是 UTF-8 编码，这可能会导致 json_encode() 失败。

关于 echo 的说明

所有值对象和集合都有一个 __toString() 方法，它将自动显示它们的 JSON 表示形式，如果 echo 或打印到屏幕上，因此您不需要 var_dump()。您应该知道，当创建对象时，json 不是实际返回的值，而是它的字符串表示形式，因此可以像正常对象一样使用所有方法。

关于克隆的说明

包含对象属性的课程是深度克隆的，因此那些对象属性本身也是克隆。

craigh / imap-mail-manager

维护者

详情