smart/emailreader

Email reader and dispatcher powered by Gearman

0.1.2 2019-01-21 21:58 UTC

Requires

• php: >=5.6
• psr/log: ~1
• sinergi/token: <1
• symfony/console: ~2
• tedivm/fetch: 0.6.*
• willdurand/email-reply-parser: ~2.3

Requires (Dev)

• phpunit/phpunit: ~4

MIT

• Kevin Gilbert

• email
• dispatcher
• reader

README

This library will read emails of a specific mailbox, will parse them and finally, dispatch them to handlers. How to install

This library is used to read email (you can inject your own by implementing the DriverInterface) : https://github.com/tedious/Fetch

Inside our Fetch driver, we used this library to parse the last email reply : https://github.com/willdurand/EmailReplyParser

##How is it working ?

1. This library contains a command which is gonna check all new emails in your mailbox and give them to gearman. 1 new email = 1 new task on gearman.
2. The gearman job will read the email, parse it and then, dispatch it to your application.
3. Once gearman is finished with this email, the email is move to another folder to mark it as processed.

##configuration

###example :

use Smart\EmailReader\Config\EmailServerConfig;

$configs = (EmailServerConfig())
    ->setDomain('imap.gmail.com')
    ->setPort(993)
    ->setService(EmailServerConfig::IMAP)
    ->setUsername('[e-mail]')
    ->setPassword('my_plain_text_password')
    ->setMainMailbox('INDEX')
    ->setProcessedMailbox('Processed');

##Dispatch

This library come with a dispatcher base class which allows you to handle different kind of email. The handlers on the dispatcher work like a router on the email subject.

###example

Imagine we have support ticket system on our app. We want our customer to be able to reply directly to the email to add their reply in our ticket system.

use Smart\EmailReader\Dispatcher\Dispatcher;

class DispatcherApp extends Dispatcher
{
    public function __construct()
    {
        $this->addDispatcher(new SupportEmailDispatcher());
        //you can add as many dispatchers as you want....
    }
}

use Smart\EmailReader\Dispatcher\Dispatcher;
use Smart\EmailReader\EmailEntity;

class SupportEmailDispatcher extends Dispatcher
{
    public function __construct()
    {
        $this->addHandler('#\[support\-(?<id>[0-9]+)\]#i', [$this, 'handleNewReply']);
    }
    
    public function handleNewReply($matches, EmailEntity $email)
    {
        $ticketId = isset($matches['id']) ? (int)$matches['id'] : null;
        $newReply = $email->getLastReply();
        //your logic here...
    }
}

###About dispatchers :

• The dispatcher don't stop at the first match, different regexs can overlap themself
• If you return false on a dispatcher, the dispatcher will stop there and complete the task
• Currently, you can only dispatch the email based on the subject

##Installation

###Dependencies

This should be place in your app container

$emailReader = new Fetch(
    new EmailServerConfig() //check the configuration section
); 

$emailLoggerLogger = new EmailReaderLogger(
    '/log/path_to_your_log_file'
);

###Gearman job

We use Sinergi gearman : https://github.com/sinergi/gearman

//add this in sinergi gearman :

new EmailReaderDispatchJob(
    $emailReader,
    new DispatcherApp(), //your own dispatcher
    $emailLoggerLogger
);

###Register Command

We use symfony console : https://github.com/symfony/Console

$consoleApp = new ConsoleApplication();
$gearmanDispatcher = '...'; //get your gearman dispatcher

$consoleApp->add(
    new EmailReaderSendCommand(
        $gearmanDispatcher,
        $emailReader
    )
);

Finally, you just need to add a cron on that command every few minutes to read incoming email and dispatch them into your application.