php-imap 参考手册

1. 相关资料

composer require php-imap/php-imap

名称	地址
Packagist	https://packagist.org/packages/php-imap/php-imap

2. php-imap 成员

2.1 构造方法

参数	说明	示例
$imapPath	服务地址	{imap.163.com:143}
$login	登录名	[email protected]
$password	登录密码	***
$attachmentsDir	附件存储目录 ，如果设置了这个参数 ，邮件中的附件会自动存储到这个目录	-
$serverEncoding	服务器使用的字符编码	-

/**
 * @param string $imapPath
 * @param string $login
 * @param string $password
 * @param string $attachmentsDir
 * @param string $serverEncoding
 *
 * @throws InvalidParameterException
 */
public function __construct($imapPath, $login, $password, $attachmentsDir = null, $serverEncoding = 'UTF-8')
{
    $this->imapPath = trim($imapPath);
    $this->imapLogin = trim($login);
    $this->imapPassword = $password;
    $this->setServerEncoding($serverEncoding);
    if (null != $attachmentsDir) {
        $this->setAttachmentsDir($attachmentsDir);
    }
}

2.2 邮件信息相关的成员

成员	所属类	说明	示例
searchMailbox(disableServerEncoding = false)	PhpImap\Mailbox	根据 criteria 参数参见 https://www.php.net/imap_search	-
getMail(markAsSeen = true)	PhpImap\Mailbox	根据邮件的 $mailId 获取邮件数据 ，如果获取了附件并设置了附件的默认存储路径 ，它会自动将邮件附件保存到该路径 ，返回 PhpImap\IncomingMail 实例	-
getMailHeader($mailId)	PhpImap\Mailbox	根据邮件的 $mailId 获取邮件数据 ，返回 PhpImap\IncomingMailHeader 实例	-
getMailsInfo(array $mailsIds)	PhpImap\Mailbox	获取一组邮件的信息	Array ( [0] => stdClass Object ( [subject] => test [from] => 苍松 拔雨 [to] => "[email protected]" [date] => Sun, 5 Jan 2020 22:39:23 +0000 [message_id] => [size] => 7364 [uid] => 1524851185 [msgno] => 1 [recent] => 0 [flagged] => 0 [answered] => 0 [deleted] => 0 [seen] => 0 [draft] => 0 [udate] => 1578263965 ) )
$textPlain	PhpImap\IncomingMail	以普通文本格式返回邮件内容	-
$textHtml	PhpImap\IncomingMail	以 HTML 格式返回邮件内容	-
embedImageAttachments()	PhpImap\IncomingMail	将 $textHtml 中的图片转为 base64	-
getRawMail(markAsSeen = true)	PhpImap\Mailbox	返回邮件的原始数据信息	-
getMailMboxFormat($mailId)	PhpImap\Mailbox	以 MBOX 格式返回邮件内容	-

2.3 邮件附件相关的成员

成员	所属类	说明	示例
hasAttachments()	PhpImap\IncomingMail	如果邮件中有附件返回 true	-
getAttachments()	PhpImap\IncomingMail	返回一个数组 ，数组的每一项都是 PhpImap\IncomingMailAttachment 实例	-
removeAttachment($id)	PhpImap\IncomingMail	根据附件的 id 删除附件（ 不会删除文件 ）	-
setAttachmentsIgnore($attachmentsIgnore)	PhpImap\Mailbox	设置是否获取邮件中的附件	-
getAttachmentsIgnore()	PhpImap\Mailbox	返回 bool ，true 表示是否自动获取附件	-
setAttachmentsDir($attachmentsDir)	PhpImap\Mailbox	设置附件的存储路径	-
getAttachmentsDir()	PhpImap\Mailbox	返回当前设置的附件存储路径	-
$id	PhpImap\IncomingMailAttachment	附件的 id	08fda0244b5397e030ee401fd2bea5b24f78a72b
$name	PhpImap\IncomingMailAttachment	附件的文件名称	imap.jpg
$file_path	PhpImap\IncomingMailAttachment	附件的存储路径 ，访问这个值时应该使用属性名 filePath ，否则会抛出一个 Notice	/var/www/uploads/1524851183_08fda0244b5397e030ee401fd2bea5b24f78a72b_2.jpg
getMimeType()	PhpImap\IncomingMailAttachment	返回附件的 MIME 类型	image/jpeg; charset=binary
getContents()	PhpImap\IncomingMailAttachment	返回附件的内容	-
setFilePath($filePath)	PhpImap\IncomingMailAttachment	设置附件的存储路径 ，即 $file_path	-
saveToDisk()	PhpImap\IncomingMailAttachment	根据 $file_path 将附件存储到磁盘 ，成功返回 true	-

2.4 邮箱信息相关的成员

成员	所属类	说明	示例
getListingFolders($pattern = '*')	PhpImap\Mailbox	返回邮箱中列出的文件夹列表	-
countMails()	PhpImap\Mailbox	获取邮箱中邮件的数量	-
getMailboxes($search = '*')	PhpImap\Mailbox	返回邮箱中所有的文件夹列表	-
checkMailbox()	PhpImap\Mailbox	返回当前邮箱相关的信息	-

2.5 设置邮件的成员

成员	所属类	说明	示例
deleteMail($mailId)	PhpImap\Mailbox	根据 $mailId 删除邮件	-
setFlag(array flag)	PhpImap\Mailbox	设置一组邮件的标记 ，可用的值有 RFC2060 规定的 \Seen 、\Answered 、\Flagged 、 \Deleted 、\Draft	-
clearFlag(array flag)	PhpImap\Mailbox	删除一组邮件的标记 ，可用的值有 RFC2060 规定的 \Seen 、\Answered 、\Flagged 、 \Deleted 、\Draft	-
markMailsAsImportant(array $mailId)	PhpImap\Mailbox	将邮件标记为 \Flagged	-
markMailAsRead($mailId)	PhpImap\Mailbox	将邮件标记为 \Seen	-
markMailsAsRead(array $mailId)	PhpImap\Mailbox	将一组邮件标记为 \Seen	-
markMailAsUnread($mailId)	PhpImap\Mailbox	删除邮件的标记 \Seen	-
markMailsAsUnread(array $mailId)	PhpImap\Mailbox	删除一组邮件的标记 \Seen	-

2.6 连接相关的成员

成员	所属类	说明	示例
disconnect()	PhpImap\Mailbox	与 IMAP 服务器断开连接	-
getLogin()	PhpImap\Mailbox	返回 IMAP 登录信息 ，通常是邮件地址	[email protected]
getImapPath()	PhpImap\Mailbox	返回 IMAP 路径	{imap.163.com:143}

2.7 其他配置相关的成员

成员	所属类	说明	示例
setServerEncoding($serverEncoding)	PhpImap\Mailbox	设置服务器使用的编码	-
getServerEncoding()	PhpImap\Mailbox	返回当前设置的服务器编码	-

3. IncomingMailHeader

getMailHeader() 方法会返回邮件的 IncomingMailHeader 实例 ，下面看可以从 IncomingMailHeader 中提取到哪些信息

属性	说明	示例
id	邮件的 id	1524851188
date	邮件的发送时间	2020-01-07T02:04:27+08:00
headersRaw	邮件的原数据	-
headers	邮件原数据中提取出的数据	-
subject	邮件的主题	-
fromHost	发件人 host	qq.com
fromName	发件人名称	-
fromAddress	发件人邮箱	[email protected]
senderHost	收件人 host	163.com
senderName	收件人名称	-
senderAddress	收件人邮箱	[email protected]
to	收件人数组	[to] => Array([[email protected]] => cangsongbayu)
cc	抄送人数组	[cc] => Array([[email protected]] => cangsongbayu)
bcc	密送人数组	[bcc] => Array()
replyTo	回复人数组	[replyTo] => Array([[email protected]] => cangsongbayu)
headers->date	邮件的发送时间	Tue, 7 Jan 2020 02:42:27 +0800
headers->subject	邮件的主题 ，可能未解码	=?gb18030?B?suLK1MPXy8mzrcvN?=
headers->toaddress	收件人名称 ，可能未解码	=?gb18030?B?Y2FuZ3NvbmdiYXl1?=
headers->to	收件人数组 ，数组中每一项都是 stdClass ，分别有 personal 、mailbox 、host 三个属性	Array ( [0] => stdClass Object ( [personal] => =?gb18030?B?Y2FuZ3NvbmdiYXl1?= [mailbox] => cangsongbayu [host] => 163.com ) )
headers->fromaddress	发件人名称 ，可能未解码	?gb18030?B?stTLybDO0+o=?= [email protected]
headers->from	发件人数组 ，数组中每一项都是 stdClass ，分别有 personal 、mailbox 、host 三个属性	Array ( [0] => stdClass Object ( [personal] => =?gb18030?B?stTLybDO0+o=?= [mailbox] => 1228950011 [host] => qq.com ) )
headers->ccaddress	抄送人名称 ，可能是未解码	?gb18030?B?Y2FuZ3NvbmdiYXl1?=
headers->cc	抄送人数组 ， 数组中每一项都是 stdClass ，分别有 personal 、mailbox 、host 三个属性	Array ( [0] => stdClass Object ( [personal] => =?gb18030?B?Y2FuZ3NvbmdiYXl1?= [mailbox] => cangsongbayu [host] => 163.com ) )
headers->reply_toaddress	回复人名称 ，可能未解码	?gb18030?B?stTLybDO0+o=?= [email protected]
headers->reply_to	回复人数组 ， 数组中每一项都是 stdClass ，分别有 personal 、mailbox 、host 三个属性	Array ( [0] => stdClass Object ( [personal] => =?gb18030?B?stTLybDO0+o=?= [mailbox] => 1228950011 [host] => qq.com ) )
headers->senderaddress	发件人名称 ，可能未解码	?gb18030?B?stTLybDO0+o=?= [email protected]
headers->sender	发件人数组 ， 数组中每一项都是 stdClass ，分别有 personal 、mailbox 、host 三个属性	Array ( [0] => stdClass Object ( [personal] => =?gb18030?B?stTLybDO0+o=?= [mailbox] => 1228950011 [host] => qq.com ) )

4. 返回值一览

4.1 PhpImap\Mailbox 的 checkMailbox() 的返回值

返回一个 stdClass

stdClass Object
(
    [Date] => Mon, 6 Jan 2020 06:45:48 +0800
    [Driver] => imap
    [Mailbox] => {imap.163.com:143/imap/tls/user="[email protected]"}INBOX
    [Nmsgs] => 2
    [Recent] => 2
)

成员	说明	示例
Date	根据 RFC2822 格式化的当前系统时间	Mon, 6 Jan 2020 05:46:26 +0800
Dirver	访问此邮箱使用的协议	POP3 、IMAP 、NNTP
MailBox	邮箱名称	{imap.163.com:143/imap/tls/user="[email protected]"}INBOX
Nmsgs	邮箱中的邮件数量	1
Recent	邮箱中最近的邮件数量	0

4.2 PhpImap\Mailbox 的 getMailsInfo(array $mailsIds) 的返回值

返回的数组中每一项都是 stdClass ，包含了对应邮件的一些描述信息

Array
(
    [0] => stdClass Object
        (
            [subject] => test
            [from] => 苍松 拔雨 
            [to] => "[email protected]" 
            [date] => Sun, 5 Jan 2020 22:39:23 +0000
            [message_id] =>    
            [size] => 7364
            [uid] => 1524851185
            [msgno] => 1
            [recent] => 0
            [flagged] => 0
            [answered] => 0
            [deleted] => 0
            [seen] => 0
            [draft] => 0
            [udate] => 1578263965
        )

    [1] => stdClass Object
        (
            [subject] => test subject
            [from] => " 苍松拔雨 " <[email protected]>
            [to] => " cangsongbayu " 
            [date] => Mon, 6 Jan 2020 06:41:46 +0800
            [message_id] => 
            [size] => 2324
            [uid] => 1524851186
            [msgno] => 2
            [recent] => 0
            [flagged] => 0
            [answered] => 0
            [deleted] => 0
            [seen] => 0
            [draft] => 0
            [udate] => 1578264108
        )

)

成员	说明	示例
subject	邮件主题	-
from	发件人名称	-
sender	发件人邮箱 ，不一定有	-
to	收件人 ，不一定是邮箱地址	-
date	发送时间	Mon, 6 Jan 2020 06:41:46 +0800
size	邮件的字节大小	-
uid	邮箱中邮件的 uid	-
msgno	邮箱中的邮件序列号	-
recent	表示邮件是否被标记为 \Recent	-
flagged	表示邮件是否被标记为 \Flagged	-
answered	表示邮件是否被标记为 \Answered	-
deleted	表示邮件是否被标记为 \Deleted	-
seen	表示邮件是否被标记为 \Seen	-
draft	表示邮件是否被标记为 \Draft	-
udate	Unix 时间戳格式的 date	-

4.3 PhpImap\Mailbox 的 getListingFolders($pattern = '*') 的返回值

返回邮箱中列出的文件夹列表

Array
(
    [0] => {imap.163.com:143}INBOX
    [1] => {imap.163.com:143}草稿箱
    [2] => {imap.163.com:143}已发送
    [3] => {imap.163.com:143}已删除
    [4] => {imap.163.com:143}垃圾邮件
    [5] => {imap.163.com:143}病毒文件夹
)

4.4 PhpImap\Mailbox 的 getMailboxes() 的返回值

返回邮箱中所有的文件夹列表

Array
(
    [0] => Array
        (
            [fullpath] => {imap.163.com:143}INBOX
            [attributes] => 0
            [delimiter] => /
            [shortpath] => INBOX
        )

    [1] => Array
        (
            [fullpath] => {imap.163.com:143}草稿箱
            [attributes] => 0
            [delimiter] => /
            [shortpath] => 草稿箱
        )

    [2] => Array
        (
            [fullpath] => {imap.163.com:143}已发送
            [attributes] => 0
            [delimiter] => /
            [shortpath] => 已发送
        )

    [3] => Array
        (
            [fullpath] => {imap.163.com:143}已删除
            [attributes] => 0
            [delimiter] => /
            [shortpath] => 已删除
        )

    [4] => Array
        (
            [fullpath] => {imap.163.com:143}垃圾邮件
            [attributes] => 0
            [delimiter] => /
            [shortpath] => 垃圾邮件
        )

    [5] => Array
        (
            [fullpath] => {imap.163.com:143}病毒文件夹
            [attributes] => 0
            [delimiter] => /
            [shortpath] => 病毒文件夹
        )

)

5. 参数补充说明

5.1 PhpImap\Mailbox 的 setFlag(array flag) 参数说明

参数	说明	示例
$mailsIds	邮件的 $mailId 组成的数组	-
$flag	可用的值有 RFC2060 规定的 \Seen 、\Answered 、\Flagged 、 \Deleted 、\Draft	-

标记	说明	示例
\Seen	将邮件标记为已读	mailsIds, '\Seen')
\Deleted	将邮件标记为已删除	mailsIds, '\Deleted')
\Draft	将邮件标记为草案	mailsIds, '\Draft')
\Flagged	将邮件标记为重要邮件	mailsIds, '\Flagged')