README

为 Symfony 提供简单的 php-imap 集成。

兼容性矩阵

想要支持这个包吗？

考虑使用我们位于 codito.io 的 随机代码生成器 服务。

使用 codito.io，您可以免费生成最多 250,000 个您选择的格式代码。您可以将生成的代码用于促销代码（例如，可以将其打印在包装内部）、序列号、一次性或多用密码、彩票券、折扣代码、券、随机字符串等 - 更多用例请参阅我们的 示例。如果您需要的代码数量超过 250,000 个，您可以使用我们的 商业代码生成服务。

安装

1. Composer

从命令行运行

composer require secit-pl/imap-bundle

配置

要设置您的邮箱配置，打开 config/packages/imap.yaml 并调整其内容。

以下是一个示例配置

imap:
    connections:
        example:
            imap_path: "{localhost:993/imap/ssl/novalidate-cert}INBOX"
            username: "email@example.com"
            password: "password"

        another:
            imap_path: "{localhost:143}INBOX"
            username: "username"
            password: "password"
            attachments_dir: "%kernel.project_dir%/var/imap/attachments"
            server_encoding: "UTF-8"

        full_config:
            imap_path: "{localhost:143}INBOX"
            username: "username"
            password: "password"
            attachments_dir: "%kernel.project_dir%/var/imap/attachments"
            create_attachments_dir_if_not_exists: true # default true
            created_attachments_dir_permissions: 777 # default 770
            server_encoding: "UTF-8"
            enabled: true

如果您使用 Symfony 连接到 Microsoft 365 商业环境，您可能会想连接到共享邮箱。在这种情况下，您需要指定参数 authuser 和 user。其中 shared_account 是不带域的用户名，例如

imap:
    connections:
        example:
            imap_path: "{outlook.office365.com:993/imap/ssl/authuser=first.last@example.com/user=shared_account}Root/Folder"
            username: "email@example.com"
            password: "password"

安全

不要在配置文件中直接设置敏感数据，如邮箱、用户名和密码。您可能需要 编码值。 基于环境变量的配置 在配置文件中引用机密 更好地设置它们在 .env.local 中，使用 Symfony Secrets 或 CI-Secrets。

imap:
    connections:
        example:
            imap_path:  '%env(EXAMPLE_CONNECTION_MAILBOX)%'
            username: '%env(EXAMPLE_CONNECTION_USERNAME)%'
            password: '%env(EXAMPLE_CONNECTION_PASSWORD)%'

实际配置转储

php bin/console debug:config imap

验证邮箱是否可以正确连接

php bin/console secit:imap:validate-connections

结果

+------------------+---------------------+---------------------------------+--------------------+---------+
| Connection       | Connect Result      | Mailbox                         | Username           | Enabled |
+------------------+---------------------+---------------------------------+--------------------+---------+
| example          | SUCCESS             | {imap.example.com:993/imap/ssl} | user@mail.com      | YES     |
| example_WRONG    | FAILED: Reason..... | {imap.example.com:993/imap/ssl} | WRONG              | YES     |
| example_DISABLED | DISABLED            | {imap.example.com:993/imap/ssl} | user2@mail.com     | NO      |
+------------------+---------------------+---------------------------------+--------------------+---------+

如果任何连接失败，此命令可能需要一些时间。这是因为长时间的连接超时。如果您在 CI-Pipeline 中使用此命令，请添加参数 -q。出于安全原因，密码不会显示。您可以设置一个连接数组以进行验证。

php bin/console secit:imap:validate-connections example example2

用法

假设您的配置如下所示

imap:
    connections:
        example:
            imap_path: ...
            
        second:
            imap_path: ...
            
        connection3:
            imap_path: ...

您可以通过使用服务 自动装配 并使用 camelCased 连接名称 + Connection 作为参数名称来在类内部获取连接。

<?php

namespace App\Controller;

use SecIT\ImapBundle\ConnectionInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class IndexController extends AbstractController
{
    public function index(
        ConnectionInterface $exampleConnection,
        ConnectionInterface $secondConnection,
        ConnectionInterface $connection3Connection,
    ) {
        $mailbox = $exampleConnection->getMailbox(); // instance of PhpImap\Mailbox
        $isConnectable = $secondConnection->testConnection();
        $connectionName = $connection3Connection->getName(); // connection3

        ...
    }

    ...
}

也可以通过它们的名称和 目标 属性注入连接

<?php

namespace App\Controller;

use SecIT\ImapBundle\ConnectionInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\Target;

class IndexController extends AbstractController
{
    public function index(
        #[Target('exampleConnection')] 
        ConnectionInterface $example,
        #[Target('secondConnection')] 
        ConnectionInterface $customName,
        #[Target('connection3Connection')] 
        ConnectionInterface $connection,
    ) {
        $mailbox = $exampleConnection->getMailbox(); // instance of PhpImap\Mailbox
        $isConnectable = $secondConnection->testConnection();
        $connectionName = $connection3Connection->getName(); // connection3

        ...
    }

    ...
}

要获取所有连接，您可以使用 自动装配迭代器

<?php

namespace App\Controller;

use SecIT\ImapBundle\ConnectionInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\AutowireIterator;

class IndexController extends AbstractController
{
    public function index(
        #[AutowireIterator('secit.imap.connection')]
        iterable $connections,
    ) {
        foreach ($connections as $connection) {
            $mailbox = $connection->getMailbox();
        }

        ...
    }

    ...
}

从这一点开始，您可以使用由 php-imap 库提供的任何方法。例如

$mailbox = $exampleConnection->getMailbox();
$mailbox->getMailboxInfo();

要快速测试与服务器的连接，您可以使用 testConnection() 方法

// testing with a boolean response
$isConnectable = $exampleConnection->testConnection();
var_dump($isConnectable);

// testing with a full error message
try {
    $isConnectable = $exampleConnection->testConnection(true);
} catch (\Exception $exception) {
    echo $exception->getMessage();
}

请注意，这将断开您当前的连接，并在成功时创建一个新的连接。在大多数情况下，这不是问题。

迁移指南

版本 3.0.0 引入了一些 BC 断开。

配置

为了更好地匹配 PhpImap\Mailbox 构造函数参数，将 mailbox 配置参数重命名为 imap_path。

上一个版本

imap:
    connections:
        example_connection:
            mailbox: ...
            username: ...
            password: ...

当前版本

imap:
    connections:
        example:
            imap_path: ...
            username: ...
            password: ...

获取连接

之前要获取连接，您必须注入 SecIT\ImapBundle\Service\Imap 服务并从中获取连接。

public function index(Imap $imap)
{
    $mailbox = $imap->get('example_connection')->getConnection();
}

迁移后，您应该使用 autowiring 来注入每个连接动态创建的服务

use SecIT\ImapBundle\Connection\ConnectionInterface;

public function index(ConnectionInterface $exampleConnection)
{
    $mailbox = $exampleConnection->getMailbox();
}

或使用 Target 属性

use SecIT\ImapBundle\ConnectionInterface;
use Symfony\Component\DependencyInjection\Attribute\Target;

public function index(
    #[Target('exampleConnection')] 
    ConnectionInterface $customName,
) {
    $mailbox = $customName->getMailbox();
}

控制台命令

命令的名称从 imap-bundle:validate 更改为 secit:imap:validate-connections。