README

IMAP/POP3-Watcher for E-Documents

Note

Caution

This library is currently still considered experimental and should therefore be used with caution. I would be happy for an issue to be posted if bugs are found.

License

The code in this project is provided under the MIT license.

Overview

With this library it is possible to monitor mail accounts (IMAP and POP3) and to check and process incoming electronic invoice documents (ZUGFeRD PDF and XML).

Dependencies

This package makes use of

Installation

There is one recommended way to install horstoeko/zugferdmail via Composer:

composer require horstoeko/zugferdmail

Usage

For detailed eplanation you may have a look in the examples of this package and the documentation attached to every release.

First, it is necessary to configure the library so that it is aware of the mail accounts to be checked. For IMAP accounts, the folders to be monitored must also be defined. In addition, any actions (handlers) can be defined for each mail account.

Configuration

First you need to create a configuration instance:

$config = new ZugferdMailConfig();

The mail accounts to be monitored must then be defined. You can also specify the folders and mimetypes to be checked:

$account1 = $config->addAccount('demo', '192.168.1.1', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');
$account1->addFolderToWatch('INBOX');
$account1->addFolderToWatch('somefolder/somesubfolder');
$account1->addMmimeTypeToWatch('application/pdf');
$account1->addMmimeTypeToWatch('text/xml');

Last but not least, the actions (handlers) to be performed are specified for each mail account, which are executed when a ZUGFeRD or XML document is found. Some of these handlers are already available, but you can also define your own actions:

$account1->addHandler(new ZugferdMailHandlerMoveMessage('Invoice/Incoming'));
$account1->addHandler(new ZugferdMailHandlerSaveToFile('/tmp', 'invoice.att'));

You can also define callbacks to call when a document was found. If such a callback function returns the value false, then all remaining callback functions are not called:

$account1->addCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {
    $document->getDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);
    echo "Document found ... " . PHP_EOL;
    echo "Document No. ..... " . $documentno . PHP_EOL;
});

Please note that the callbacks are neither loaded from a configuration file nor saved in one.

Check mail accounts for matching mails:

To perform the actual handling of all mail accounts, instantiate the class ZugferdMailReader, to which the configuration is passed. The monitoring is started by calling the method checkAllAccounts

$reader = new ZugferdMailReader($config);
$reader->checkAllAccounts();

Predefined handlers

Implement your own handler

It is quite easy to implement your own action (handler). To do this, define your own class which extends a class from ZugferdMailHandlerAbstract. This abstract class defines a single method handleDocument, which is passed information about the folder, message, attachment and the e-invoice document:

public function handleDocument(
    ZugferdMailAccount $account,
    Folder $folder,
    Message $message,
    Attachment $attachment,
    ZugferdDocumentReader $document,
    int $recognitionType
);

An example:

use horstoeko\zugferd\ZugferdDocumentReader;
use horstoeko\zugferdmail\config\ZugferdMailAccount;
use Webklex\PHPIMAP\Attachment;
use Webklex\PHPIMAP\Folder;
use Webklex\PHPIMAP\Message;

class MyOwnHandler extends ZugferdMailHandlerAbstract
{
    public function handleDocument(
        ZugferdMailAccount $account,
        Folder $folder,
        Message $message,
        Attachment $attachment,
        ZugferdDocumentReader $document,
        int $recognitionType)
    {
        // Do some stuff
    }
}

The parameter $recognitionType is one of the constants from ZugferdMailReaderRecognitionType

A small example

A possible implementation could look like this, for example:

use Webklex\PHPIMAP\Folder;
use Webklex\PHPIMAP\Message;
use Webklex\PHPIMAP\Attachment;
use horstoeko\zugferd\ZugferdDocumentReader;
use horstoeko\zugferdmail\ZugferdMailReader;
use horstoeko\zugferdmail\config\ZugferdMailConfig;
use horstoeko\zugferdmail\config\ZugferdMailAccount;
use horstoeko\zugferdmail\handlers\ZugferdMailHandlerSaveToFile;

require dirname(__FILE__) . "/../vendor/autoload.php";

$config = new ZugferdMailConfig();

$account1 = $config->addAccount('de', '127.0.0.1', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');
$account1->addFolderToWatch('Accounts/invoice@mydomain.com');
$account1->addMimeTypeToWatch('application/pdf');
$account1->addMimeTypeToWatch('text/xml');
$account1->addHandler(new ZugferdMailHandlerSaveToFile('/tmp', 'file.xml'));
$account1->addCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {
    $document->getDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);
    // Some business logic here...
});

$account2 = $config->addAccount('de', '172.10.10.10', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');
$account2->addFolderToWatch('Accounts/invoice@otheromain.com');
$account2->addMimeTypeToWatch('application/pdf');
$account2->addMimeTypeToWatch('text/xml');
$account1->addCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {
    $document->getDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);
    // Some other business logic here...
});

$reader = new ZugferdMailReader($config);
$reader->checkAllAccounts();

Console

This library also includes a console application with which it is possible to carry out corresponding operations via shell. To get an overview of the existing commands from the “zfmail” namespace, use:

./vendor/bin/ZugferdMailConsole list

Start monitoring a mailbox

The command zfmail:processmailboxfolders is available for monitoring a mailbox via shell:

./vendor/bin/ZugferdMailConsole zfmail:processmailboxfolders [options]

This has the following parameters:

Example usage

./vendor/bin/ZugferdMailConsole zfmail:processmailboxfolders \
  --host 127.0.0.1 \
  --port 993 \
  --username demouser \
  --password demopassword \
  --folder=INBOX \
  --mimetype=application/pdf \
  --mimetype=text/xml \
  --handler="horstoeko\zugferdmail\handlers\ZugferdMailHandlerCli" \
  --handler="horstoeko\zugferdmail\handlers\ZugferdMailHandlerSaveToFile,/tmp" \
  --enableublsupport

horstoeko / zugferdmail

Maintainers

Details