README

Simple ImapEngine integration for Symfony using directorytree/imapengine.

Compatibility matrix

Installation

1. Composer

From the command line run

composer require bartv2/imap-bundle

Configuration

To set up your mailbox configuration open the config/packages/imap.yaml and adjust its content.

Here is the example configuration:

imap:
    mailboxes:
        example:
            host: "imap.example.com"
            port: 993
            username: "email@example.com"
            password: "password"
            encryption: "ssl"
            validate_cert: false

        another:
            host: "imap.example.com"
            port: 143
            username: "username"
            password: "password"
            encryption: "starttls"

        full_config:
            host: "imap.example.com"
            port: 993
            timeout: 30
            debug: false
            username: "username"
            password: "password"
            encryption: "ssl"
            validate_cert: true
            authentication: "plain"
            proxy:
                socket: null
                username: null
                password: null
                request_fulluri: false

See ImapEngine Configuration page for more examples.

Security

It's good practice to do not set the sensitive data like mailbox, username and password directly in the config-files. You may have to encode the values. Configuration Based on Environment Variables Referencing Secrets in Configuration Files Better set them in .env.local, use Symfony Secrets or CI-Secrets.

imap:
    mailboxes:
        example:
            host: '%env(EXAMPLE_MAILBOX_HOST)%'
            port: '%env(int:EXAMPLE_MAILBOX_PORT)%'
            username: '%env(EXAMPLE_MAILBOX_USERNAME)%'
            password: '%env(EXAMPLE_MAILBOX_PASSWORD)%'
            encryption: '%env(EXAMPLE_MAILBOX_ENCRYPTION)%'

Dump actual config:

php bin/console debug:config imap

Validate if the mailboxes can connect correct

php bin/console bartv2:imap:validate-mailboxes

Result:

+------------------+---------------------+---------------------------+--------------------+
| Mailbox       | Connect Result      | Mailbox                   | Username           |
+------------------+---------------------+---------------------------+--------------------+
| example          | SUCCESS             | imap.example.com:993      | user@mail.com      |
| example_WRONG    | FAILED: Reason..... | imap.example.com:993      | WRONG              |
+------------------+---------------------+---------------------------+--------------------+

This command can take some while if any connection failed. That is because of a long connection-timeout. If you use this in CI-Pipeline add the parameter -q. Password is not displayed for security reasons. You can set an array of mailboxes to validate.

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

Usage

Let's say your config looks like this

imap:
    mailboxes:
        example:
            username: ...

        second:
            username: ...

You can get the mailbox inside a class by using service autowiring and using camelCased mailbox name + Mailbox as parameter name.

<?php

namespace App\Controller;

use DirectoryTree\ImapEngine\MailboxInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class IndexController extends AbstractController
{
    public function index(
        MailboxInterface $exampleMailbox,
        MailboxInterface $secondMailbox,
    ) {
        $inbox = $exampleMailbox->inbox(); // instance of FolderInterface
        $capabilities = $secondMailbox->capabilities();

        // ...
    }

    // ...
}

Mailboxes can also be injected thanks to their name and the Target attribute:

<?php

namespace App\Controller;

use DirectoryTree\ImapEngine\MailboxInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\Target;

class IndexController extends AbstractController
{
    public function index(
        #[Target('exampleMailbox')]
        MailboxInterface $example,
        #[Target('secondMailbox')]
        MailboxInterface $customName,
    ) {
        $inbox = $example->inbox();
        $folders = $customName->folders();

        // ...
    }

    // ...
}

To get all mailboxes you can use AutowireIterator

<?php

namespace App\Controller;

use DirectoryTree\ImapEngine\MailboxInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\AutowireIterator;

class IndexController extends AbstractController
{
    public function index(
        #[AutowireIterator('bartv2.imap.mailbox')]
        iterable $mailboxes,
    ) {
        /** @var MailboxInterface $mailbox */
        foreach ($mailboxes as $mailbox) {
            $mailbox->connection();
        }

        // ...
    }

    // ...
}

From this point you can use any of the methods provided by the ImapEngine library. For example

/** @var FolderInterface $inbox */
$inbox = $exampleMailbox->inbox();
$capabilities = $exampleMailbox->capabilities();