README

描述

Laravel IMAP是集成原生php imap库到您的Laravel应用的一种简单方式。

如果您想在不使用Laravel的情况下使用此库，请访问webklex/php-imap

安装

如果尚未安装，请安装php-imap库

sudo apt-get install php*-imap php*-mbstring php*-mcrypt && sudo apache2ctl graceful

如果扩展已启用，您还可以检查phpinfo()

现在运行以下命令安装Laravel IMAP包

composer require webklex/laravel-imap

如果您正在运行Laravel >= 5.5，包发现将自动配置服务提供者和Client别名。

否则，对于Laravel <= 5.4，编辑您的config/app.php文件并
- 将以下内容添加到providers数组中
```
Webklex\IMAP\Providers\LaravelServiceProvider::class,
```
- 将以下内容添加到aliases数组中
```
'Client' => Webklex\IMAP\Facades\Client::class,
```
运行以下命令发布包配置文件config/imap.php

php artisan vendor:publish --provider="Webklex\IMAP\Providers\LaravelServiceProvider"

配置

如果您打算使用单个账户，您可能希望将以下内容添加到您的.env文件中。

IMAP_HOST=somehost.com
IMAP_PORT=993
IMAP_ENCRYPTION=ssl
IMAP_VALIDATE_CERT=true
IMAP_USERNAME=root@example.com
IMAP_PASSWORD=secret
IMAP_DEFAULT_ACCOUNT=default
IMAP_PROTOCOL=imap

支持的协议

imap — 使用IMAP [默认]
pop3 — 使用POP3
nntp — 使用NNTP

以下加密方法得到支持

false — 禁用加密
ssl — 使用SSL
tls — 使用TLS

详细的config/imap.php配置

default — 使用默认账户。它将用于任何缺少账户参数的情况。但如果默认账户缺少参数，则使用包的默认设置。设置为false以禁用此功能。
accounts — 所有可用账户
- default — 账户标识符（在这种情况下为default，但也可以是fooBar等）。
  - host — imap主机
  - port — imap端口
  - encryption — 所需加密方法
  - validate_cert — 决定您是否想要验证证书
  - username — imap账户用户名
  - password — imap账户密码
options — 额外的获取选项
- delimiter — 您可以使用任何支持的字符，例如"."、"/"等
- fetch — IMAP::FT_UID（通过获取消息标记为已读）或IMAP::FT_PEEK（获取消息而不设置“已读”标志）
- fetch_body — 如果设置为false，则所有消息都将获取，但没有正文和任何潜在的附件
- fetch_attachment — 如果设置为false，则所有消息都将获取，但没有附件
- fetch_flags — 如果设置为false，则所有消息都将获取，但没有任何标志
- message_key — 消息键标识选项
- fetch_order — 消息获取顺序
- open — imap_open()的特殊配置
  - DISABLE_AUTHENTICATOR — 禁用身份验证属性。
- decoder — 目前只能设置消息主题和附件名称解码器
- masks — 默认掩码配置
  - message — 默认消息掩码
  - attachment — 默认附件掩码

使用

基本使用示例

这是一个基本示例，将输出所有imap文件夹中的所有邮件，并将每条消息移动到INBOX.read。请注意，这不应在实际环境中进行测试，但它可以让人了解事物是如何工作的。

use Webklex\IMAP\Client;

$oClient = new Client([
    'host'          => 'somehost.com',
    'port'          => 993,
    'encryption'    => 'ssl',
    'validate_cert' => true,
    'username'      => 'username',
    'password'      => 'password',
    'protocol'      => 'imap'
]);
/* Alternative by using the Facade
$oClient = Webklex\IMAP\Facades\Client::account('default');
*/

//Connect to the IMAP Server
$oClient->connect();

//Get all Mailboxes
/** @var \Webklex\IMAP\Support\FolderCollection $aFolder */
$aFolder = $oClient->getFolders();

//Loop through every Mailbox
/** @var \Webklex\IMAP\Folder $oFolder */
foreach($aFolder as $oFolder){

    //Get all Messages of the current Mailbox $oFolder
    /** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
    $aMessage = $oFolder->messages()->all()->get();
    
    /** @var \Webklex\IMAP\Message $oMessage */
    foreach($aMessage as $oMessage){
        echo $oMessage->getSubject().'<br />';
        echo 'Attachments: '.$oMessage->getAttachments()->count().'<br />';
        echo $oMessage->getHTMLBody(true);
        
        //Move the current Message to 'INBOX.read'
        if($oMessage->moveToFolder('INBOX.read') == true){
            echo 'Message has ben moved';
        }else{
            echo 'Message could not be moved';
        }
    }
}

门面

如果您使用\Webklex\IMAP\Facades\Client::class Facade，请先选择一个账户

use Webklex\IMAP\Facades\Client;

$oClient = Client::account('default');
$oClient->connect();

文件夹/邮箱

有一个实验性功能可以按名称获取文件夹实例。为了更方便地访问，请查看新的配置选项imap.options.delimiter，但是getFolder方法需要三个选项：必需的（字符串）$folder_name和两个可选变量。一个整数$attributes，有时是32或64（我老实说不知道这个数字是什么意思，所以请随意告诉我和其他人）以及一个分隔符，如果未设置，将使用config/imap.php文件中配置的默认选项。

/** @var \Webklex\IMAP\Client $oClient */

/** @var \Webklex\IMAP\Folder $oFolder */
$oFolder = $oClient->getFolder('INBOX.name');

列出所有可用的文件夹

/** @var \Webklex\IMAP\Client $oClient */

/** @var \Webklex\IMAP\Support\FolderCollection $aFolder */
$aFolder = $oClient->getFolders();

搜索消息

搜索特定电子邮件

/** @var \Webklex\IMAP\Folder $oFolder */

//Get all messages
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->all()->get();

//Get all messages from example@domain.com
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->from('example@domain.com')->get();

//Get all messages since march 15 2018
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since('15.03.2018')->get();

//Get all messages within the last 5 days
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since(now()->subDays(5))->get();
//Or for older laravel versions..
$aMessage = $oFolder->query()->since(\Carbon::now()->subDays(5))->get();

//Get all messages containing "hello world"
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('hello world')->get();

//Get all unseen messages containing "hello world"
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->unseen()->text('hello world')->get();

//Extended custom search query for all messages containing "hello world" 
//and have been received since march 15 2018
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('hello world')->since('15.03.2018')->get();
$aMessage = $oFolder->query()->Text('hello world')->Since('15.03.2018')->get();
$aMessage = $oFolder->query()->whereText('hello world')->whereSince('15.03.2018')->get();

// Build a custom search query
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()
->where([['TEXT', 'Hello world'], ['SINCE', \Carbon::parse('15.03.2018')]])
->get();

//!EXPERIMENTAL!
//Get all messages NOT containing "hello world"
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->notText('hello world')->get();
$aMessage = $oFolder->query()->not_text('hello world')->get();
$aMessage = $oFolder->query()->not()->text('hello world')->get();

用于更好的代码阅读的可用的搜索别名

// Folder::search() is just an alias for Folder::query()
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->search()->text('hello world')->since('15.03.2018')->get();

// Folder::messages() is just an alias for Folder::query()
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->messages()->text('hello world')->since('15.03.2018')->get();

所有可用的查询/搜索方法都可以在这里找到：Query::class

可用的搜索条件

ALL — 返回所有符合其他条件的消息
ANSWERED — 匹配设置了\ANSWERED标志的消息
BCC "string" — 匹配Bcc:字段中包含"string"的消息
BEFORE "date" — 匹配日期在"date"之前的消息
BODY "string" — 匹配消息体中包含"string"的消息
CC "string" — 匹配Cc:字段中包含"string"的消息
DELETED — 匹配已删除的消息
FLAGGED — 匹配设置了\FLAGGED（有时称为Important或Urgent）标志的消息
FROM "string" — 匹配From:字段中包含"string"的消息
KEYWORD "string" — 匹配包含"string"关键字的消息
NEW — 匹配新消息
NOT — 不匹配
OLD — 匹配旧消息
ON "date" — 匹配日期与"date"匹配的消息
RECENT — 匹配设置了\RECENT标志的消息
SEEN — 匹配已读消息（\SEEN标志已设置）
SINCE "date" — 匹配日期在"date"之后的消息
SUBJECT "string" — 匹配Subject中包含"string"的消息
TEXT "string" — 匹配包含"text"的消息
TO "string" — 匹配To中包含"string"的消息
UNANSWERED — 匹配未回答的消息
UNDELETED — 匹配未删除的消息
UNFLAGGED — 匹配未标记的消息
UNKEYWORD "string" — 匹配不包含关键字"string"的消息
UNSEEN — 匹配尚未阅读的消息

更多信息

结果限制

限制请求的电子邮件

/** @var \Webklex\IMAP\Folder $oFolder */

//Get all messages for page 2 since march 15 2018 where each apge contains 10 messages
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->since('15.03.2018')->limit(10, 2)->get();

分页

分页查询

/** @var \Webklex\IMAP\Folder $oFolder */

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $oFolder->query()->since('15.03.2018')->paginate();

分页消息集合

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $aMessage->paginate();

分页列表的Blade示例

/** @var \Webklex\IMAP\Folder $oFolder */

/** @var \Illuminate\Pagination\LengthAwarePaginator $paginator */
$paginator = $oFolder->search()
->since(\Carbon::now()->subDays(14))->get()
->paginate($perPage = 5, $page = null, $pageName = 'imap_blade_example');

<table>
    <thead>
        <tr>
            <th>UID</th>
            <th>Subject</th>
            <th>From</th>
            <th>Attachments</th>
        </tr>
    </thead>
    <tbody>
        @if($paginator->count() > 0)
            @foreach($paginator as $oMessage)
                <tr>
                    <td>{{$oMessage->getUid()}}</td>
                    <td>{{$oMessage->getSubject()}}</td>
                    <td>{{$oMessage->getFrom()[0]->mail}}</td>
                    <td>{{$oMessage->getAttachments()->count() > 0 ? 'yes' : 'no'}}</td>
                </tr>
            @endforeach
        @else
            <tr>
                <td colspan="4">No messages found</td>
            </tr>
        @endif
    </tbody>
</table>

{{$paginator->links()}}

您还可以分页Folder、Attachment或FlagCollection实例。

查看示例

您可以在/examples下找到一些blade示例。

获取特定消息

通过uid获取特定消息（请注意，uid不是唯一的，可能会变化）

/** @var \Webklex\IMAP\Folder $oFolder */

/** @var \Webklex\IMAP\Message $oMessage */
$oMessage = $oFolder->getMessage($uid = 1);

消息标志

标记或“取消标记”消息

/** @var \Webklex\IMAP\Message $oMessage */
$oMessage->setFlag(['Seen', 'Spam']);
$oMessage->unsetFlag('Spam');

在获取时标记所有消息为“已读”

/** @var \Webklex\IMAP\Folder $oFolder */
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('Hello world')->markAsRead()->get();

在获取时不要标记所有消息为“已读”

/** @var \Webklex\IMAP\Folder $oFolder */
/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->text('Hello world')->leaveUnread()->get();

附件

保存消息附件

/** @var \Webklex\IMAP\Message $oMessage */

/** @var \Webklex\IMAP\Support\AttachmentCollection $aAttachment */
$aAttachment = $oMessage->getAttachments();

$aAttachment->each(function ($oAttachment) {
    /** @var \Webklex\IMAP\Attachment $oAttachment */
    $oAttachment->save();
});

高级获取

获取不包含正文的消息（减少负载）

/** @var \Webklex\IMAP\Folder $oFolder */

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereText('Hello world')->setFetchBody(false)->get();

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereAll()->setFetchBody(false)->setFetchAttachment();

获取不包含正文、标记和附件的消息（减少负载）

/** @var \Webklex\IMAP\Folder $oFolder */

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereText('Hello world')
->setFetchFlags(false)
->setFetchBody(false)
->setFetchAttachment(false)
->get();

/** @var \Webklex\IMAP\Support\MessageCollection $aMessage */
$aMessage = $oFolder->query()->whereAll()
->setFetchFlags(false)
->setFetchBody(false)
->setFetchAttachment(false)
->get();

掩码

Laravel-IMAP自带两个默认掩码MessageMask::class和AttachmentMask::class。

掩码实例必须手动调用，旨在添加自定义功能。

您可以通过不带任何参数调用掩码方法来调用默认掩码。

/** @var \Webklex\IMAP\Message $oMessage */
$mask = $oMessage->mask();

有几个方法可以设置默认掩码

/** @var \Webklex\IMAP\Client $oClient */
/** @var \Webklex\IMAP\Message $oMessage */

$message_mask = \Webklex\IMAP\Support\Masks\MessageMask::class;

$oClient->setDefaultMessageMask($message_mask);
$oMessage->setMask($message_mask);
$mask = $oMessage->mask($message_mask);

最后一个方法不会设置掩码，而是使用提供的掩码生成一个掩码实例。

您还可以在config/imap.php文件下的masks中设置默认掩码。

您还可以在附件上应用掩码

/** @var \Webklex\IMAP\Client $oClient */
/** @var \Webklex\IMAP\Attachment $oAttachment */
$attachment_mask = \Webklex\IMAP\Support\Masks\AttachmentMask::class;

$oClient->setDefaultAttachmentMask($attachment_mask);
$oAttachment->setMask($attachment_mask);
$mask = $oAttachment->mask($attachment_mask);

如果您想实现自己的掩码，请扩展MessageMask::class、AttachmentMask::class或Mask::class并实现所需的逻辑

/** @var \Webklex\IMAP\Message $oMessage */
class CustomMessageMask extends \Webklex\IMAP\Support\Masks\MessageMask {

    /**
     * New custom method which can be called through a mask
     * @return string
     */
    public function token(){
        return implode('-', [$this->message_id, $this->uid, $this->message_no]);
    }
}

$mask = $oMessage->mask(CustomMessageMask::class);

echo $mask->token().'@'.$mask->uid;

更多示例可以在这里找到

特殊

查找包含消息的文件夹

$oFolder = $aMessage->getContainingFolder();

支持

如果您遇到任何问题或发现任何错误，请毫不犹豫地创建一个新的问题。然而，请注意，可能需要一些时间才能得到回复。

如果您需要立即或商业支持，请随时通过github@webklex.com给我发邮件。

一点提示

如果您在问题中编写源代码，请考虑正确格式化它。这会使它更容易阅读，人们也更可能评论并提供帮助：）

``` php

echo '你的php代码...';

```

将转换为

echo 'your php code...';

功能 & pull requests

每个人都可以为此项目做出贡献。每个pull request都会被考虑，但也可能被拒绝。为了避免不必要的劳动，如果您计划进行较大的更改，请首先考虑创建一个功能问题。当然，如果您只是希望有一个功能，您也可以创建一个新的功能问题；）

无关主题、粗鲁或侮辱性问题将被无通知删除。

已知问题

里程碑和即将推出的功能

Wiki!!

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件github@webklex.com而不是使用问题跟踪器。

致谢

支持者

特别感谢Jetbrains通过他们的开源许可计划支持本项目的开发。

许可证

MIT许可证（MIT）。请参阅许可证文件获取更多信息。

kqtec / laravel-imap

维护者

详细信息