README

由 Jason den Dulk 编写

用于使用 maildir 和 maildir++ 格式读写文件的类。

Maildir 是一种在计算机上存储电子邮件的常用格式。Maildir++ 是 Maildir 的扩展，用于支持多个文件夹和配额。

Maildir 规范可以在 https://cr.yp.to/proto/maildir.html 找到。

Maildir++ 规范可以在 https://www.courier-mta.org/imap/README.maildirquota.html 找到。

版本 0.6.0 的重大更改。请参阅变更日志。

这是要添加的最后一个版本。如果在一年内没有提交错误报告，我将升级到 1.0.0。

要求

PHP v5.4.0 或更高版本。

安装

composer require jaypha/maildir

使用配额

要使用配额，使用 $useQuotas 设置为 true 创建 maildir++ 子树。为了使配额正常工作，您应坚持使用 MaildirPlusPlus 方法 deliver()、move()、trash() 和 emptyTrash()。Maildir 的 save() 和 delete() 方法仍然可以工作，但配额文件将不会更新，直到调用 resetQuotas。

请记住，maildir++ 规范建议大约每十五分钟重置一次配额文件。通过调用 resetQuotas() 来这样做。

API

class Maildir

在此类中文件名的使用

在此类中，由 save() 返回的名称，以及由其他函数接受的名称，不包括标志设置。因此，尽管实际的文件名在设置和清除标志时可能会在磁盘上发生变化，但使用此类的名称不会。

静态方法

Maildir Maildir::create(string $rootDir)

创建一个 Maildir。$rootDir 必须存在。将创建子目录并返回一个 Maildir 实例。

void Maildir::destroy(string $rootDir)

销毁 maildir 结构。删除 cur、new 和 tmp 目录。不影响其他任何内容。

bool MailDir::isMaildir($dir)

测试给定的 $dir 是否包含 maildir 结构

string MailDir::createName()

根据 maildir 规范中设定的指南创建一个合适的唯一名称。

属性

string $rootDir (只读)

maildir 子树的根目录

方法

__construct(string $rootDir)

为 $rootDir 创建一个 Maildir 实例。必要的子目录必须已经存在。

string save($contents)

将 $contents 保存到 Maildir 文件中。$contents 可以是一个字符串或一个资源（流）。返回文件的名称。

void touch(string $name)

强制将 $name 的文件移动到 'cur' 目录。

bool isNew(string $name)

如果 $name 的文件尚未转移到 'cur'，则返回 true。

bool exists(string $name)

如果 $name 的文件存在于 'cur' 或 'new' 中，则返回 true。

string fetch(string $name)

检索文件的內容。文件将被移动到 'cur' 目录，但不会设置 'S' 标志。

resource fetchAsStream(string $name)

以流资源的形式检索文件的內容，适用于大文件。文件将被移动到 'cur' 目录，但不会设置 'S' 标志。

mixed getPath(string $name)

获取 $name 的文件路径。如果 $name 不在 maildir 中，则返回 false。

void delete(string $name)

删除 $name 的文件。将从 'new' 或 'cur' 目录中删除文件。

bool hasFlag(string $name, string $flag)

如果文件设置了标志，则返回 true。

void setFlag(string $name, string $flag)

设置标志

void clearFlag(string $name, string $flag)

清除标志

generator getNames()

产生在maildir中存储的名称列表。

generator getFiles()

产生在maildir中存储的文件列表，按名称索引。

generator getStreams()

与getFiles()类似，但产生流而不是文件内容。

class MaildirPlusPlus

本类中文件夹名称的使用方式。

文件夹名称使用Maildir++规范中给出的逻辑格式，利用'/'分隔符。

静态方法

MaildirPlusPlus MaildirPlusPlus::create(string $rootDir, $useQuotas = false)

创建Maildir++目录结构。创建收件箱、已发送、草稿和废件箱文件夹。

MaildirPlusPlus::destroy(string $rootDir)

销毁Maildir++结构。删除所有maildir文件夹。

属性

string $rootDir (只读)

maildir++子树的根目录

方法

__construct(string $rootDir)

为$rootDir创建一个MaildirPlusPlus实例。这将为每个文件夹以及收件箱创建Maildir实例。

Maildir createFolder(string $folderName, Maildir $parent = null)

为$foldername创建maildir文件夹。如果提供了$parent，则它将用作新文件夹的逻辑“父文件夹”。

mixed getFolder(string $folderName)

获取$folderName对应的文件夹。如果找到，则返回一个Maildir，否则返回false。

void deleteFolder(string $folderName)

移除$folderName文件夹。

mixed locate(string $name)

检索文件当前所在文件夹的名称。如果文件未找到，则返回false。

mixed deliver($contents)

尝试将文件保存到子树。如果成功，则返回名称。如果配额将被超出，则返回false。

void move(string $name, string $toFolder)

将文件移动到$toFolder。文件将始终放置在目标文件夹的当前目录中。

void trash(string $name)

将文件移动到废件箱。同时设置“T”标志。

void emptyTrash()

删除废件箱中的所有文件。

void setQuotas(mixed $sizeQuota, mixed $countQuota)

设置总文件大小和文件计数的配额。如果任一设置为null，则不会为该参数设置配额。

array getQuotas()

以关联数组形式返回由setQuotas设置的配额，'size'用于大小配额，'count'用于计数字配额。null值表示未设置配额。

void resetQuotas()

重新计算子树中所有（非废件箱）文件的总大小和数量，并将其写入maildirsize。根据maildir++规范。这应该大约每十五分钟进行一次。如果您的程序进行类似操作，则应调用此方法。

array getSizeAndCount()

使用maildirsize文件（如果正在使用配额）返回子树的总文件大小和文件计数字。

变更日志

版本 0.6.0

破坏性变更

• MaildirPlusPlus不再继承自Maildir。使用getFolder("Inbox")获取收件箱maildir。
• Maildir::makeCurrent()已被重命名为touch()，现在是公开的。
• $parentDir已更改为$rootDir。
• 已弃用的函数参数现在已被删除。

其他更改

• 配额支持！已向MaildirPlusPlus添加配额支持函数。
• 向Maildir添加了isMaildir、rootDir、getPath、fetchAsStream和getStreams。
• Maildir::createName现在是公开的。

备注

我决定让MaildirPlusPlus不再继承自Maildir，因为我认为MaildirPlusPlus代表一组Maildirs，而不是一个独立的Maildir。虽然它可以在技术上伪装成Maildir，但从语义上讲，它实际上并没有与Maildir有“是一个”的关系。因此，我出于良好的编程实践，将其移除。

版本 0.5.0

• 添加了getNames和getFiles，以便遍历maildir内容。

版本 0.4.1

• 在保存时移除了字符串约束，允许传递流。

版本 0.4.0

• 添加了定位函数。
• 移动和删除不再需要原始文件夹名称。

版本 0.3.0

• 在Maildir中添加了destroy函数。
• 添加了对maildir++的支持。

版本 0.2.0

• 添加了删除函数。
• 从Maildir中移除了trash和emptyTrash。

许可证

版权 (C) 2018-21 Jaypha。
在Boost软件许可证，版本1.0下分发。
请参阅https://boost.ac.cn/LICENSE_1_0.txt