{"id":21432269,"url":"https://github.com/horstoeko/zugferdmail","last_synced_at":"2025-10-05T19:09:11.211Z","repository":{"id":264196976,"uuid":"857333885","full_name":"horstoeko/zugferdmail","owner":"horstoeko","description":"Handle incoming mails and check them for e-invoice documents","archived":false,"fork":false,"pushed_at":"2025-03-31T03:42:12.000Z","size":236,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-21T10:24:07.966Z","etag":null,"topics":["electronic-invoices","electronic-invoicing","en16931","factur-x","imap","php","php7","php8","pop3","xrechnung","zugferd"],"latest_commit_sha":null,"homepage":"https://github.com/horstoeko/zugferdmail","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/horstoeko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-14T11:30:30.000Z","updated_at":"2025-03-31T03:42:15.000Z","dependencies_parsed_at":"2024-11-22T15:38:33.450Z","dependency_job_id":"2784e669-fdb5-4718-9ba6-ffe4fefd1240","html_url":"https://github.com/horstoeko/zugferdmail","commit_stats":null,"previous_names":["horstoeko/zugferdmail"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/horstoeko/zugferdmail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/horstoeko%2Fzugferdmail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/horstoeko%2Fzugferdmail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/horstoeko%2Fzugferdmail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/horstoeko%2Fzugferdmail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/horstoeko","download_url":"https://codeload.github.com/horstoeko/zugferdmail/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/horstoeko%2Fzugferdmail/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265297046,"owners_count":23742585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electronic-invoices","electronic-invoicing","en16931","factur-x","imap","php","php7","php8","pop3","xrechnung","zugferd"],"created_at":"2024-11-22T23:17:31.125Z","updated_at":"2025-10-05T19:09:06.143Z","avatar_url":"https://github.com/horstoeko.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IMAP/POP3-Watcher for E-Documents\n\n[![Latest Stable Version](https://img.shields.io/packagist/v/horstoeko/zugferdmail.svg?style=plastic)](https://packagist.org/packages/horstoeko/zugferdmail)\n[![PHP version](https://img.shields.io/packagist/php-v/horstoeko/zugferdmail.svg?style=plastic)](https://packagist.org/packages/horstoeko/zugferdmail)\n[![License](https://img.shields.io/packagist/l/horstoeko/zugferdmail.svg?style=plastic)](https://packagist.org/packages/horstoeko/zugferdmail)\n\n[![Build Status](https://github.com/horstoeko/zugferdmail/actions/workflows/build.ci.yml/badge.svg)](https://github.com/horstoeko/zugferdmail/actions/workflows/build.ci.yml)\n[![Release Status](https://github.com/horstoeko/zugferdmail/actions/workflows/build.release.yml/badge.svg)](https://github.com/horstoeko/zugferdmail/actions/workflows/build.release.yml)\n\n## Table of Contents\n\n- [IMAP/POP3-Watcher for E-Documents](#imappop3-watcher-for-e-documents)\n  - [Table of Contents](#table-of-contents)\n  - [Note](#note)\n  - [License](#license)\n  - [Overview](#overview)\n  - [Dependencies](#dependencies)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Configuration](#configuration)\n    - [Check mail accounts for matching mails:](#check-mail-accounts-for-matching-mails)\n    - [Predefined handlers](#predefined-handlers)\n    - [Implement your own handler](#implement-your-own-handler)\n    - [A small example](#a-small-example)\n    - [Console](#console)\n      - [Start monitoring a mailbox](#start-monitoring-a-mailbox)\n\n## Note\n\n\u003e [!CAUTION]\n\u003e 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.\n\n## License\n\nThe code in this project is provided under the [MIT](https://opensource.org/licenses/MIT) license.\n\n## Overview\n\nWith 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).\n\n## Dependencies\n\nThis package makes use of\n\n* [horstoeko/zugferd](https://github.com/horstoeko/zugferd)\n* [horstoeko/zugferdublbridge](https://github.com/horstoeko/zugferdublbridge)\n* [Webklex/php-imap](https://github.com/Webklex/php-imap)\n\n## Installation\n\nThere is one recommended way to install `horstoeko/zugferdmail` via [Composer](https://getcomposer.org/):\n\n```bash\ncomposer require horstoeko/zugferdmail\n```\n\n## Usage\n\nFor detailed eplanation you may have a look in the [examples](https://github.com/horstoeko/zugferdmail/tree/master/examples) of this package and the documentation attached to every release.\n\nFirst, 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.\n\n### Configuration\n\nFirst you need to create a configuration instance:\n\n```php\n$config = new ZugferdMailConfig();\n```\n\nThe mail accounts to be monitored must then be defined. You can also specify the folders and mimetypes to be checked:\n\n```php\n$account1 = $config-\u003eaddAccount('demo', '192.168.1.1', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');\n$account1-\u003eaddFolderToWatch('INBOX');\n$account1-\u003eaddFolderToWatch('somefolder/somesubfolder');\n$account1-\u003eaddMmimeTypeToWatch('application/pdf');\n$account1-\u003eaddMmimeTypeToWatch('text/xml');\n```\n\nLast 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:\n\n```php\n$account1-\u003eaddHandler(new ZugferdMailHandlerMoveMessage('Invoice/Incoming'));\n$account1-\u003eaddHandler(new ZugferdMailHandlerSaveToFile('/tmp', 'invoice.att'));\n```\n\nYou 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:\n\n```php\n$account1-\u003eaddCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {\n    $document-\u003egetDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);\n    echo \"Document found ... \" . PHP_EOL;\n    echo \"Document No. ..... \" . $documentno . PHP_EOL;\n});\n```\nPlease note that the callbacks are neither loaded from a configuration file nor saved in one.\n\n### Check mail accounts for matching mails:\n\nTo 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```\n\n```php\n$reader = new ZugferdMailReader($config);\n$reader-\u003echeckAllAccounts();\n```\n\n### Predefined handlers\n\n| Class | Description |\n| :------ | :------ |\n| ZugferdMailHandlerNull | _Does not perform any operations_ |\n| ZugferdMailHandlerCli | _Displays brief information about the e-invoice document found on the console_ |\n| ZugferdMailHandlerCopyMessage | _Copies the message to another (different) directory_ |\n| ZugferdMailHandlerMoveMessage| _Moves the message to another (different) directory_ |\n| ZugferdMailHandlerDeleteMessage | _Deletes the message_ |\n| ZugferdMailHandlerMarkSeenMessage | _Marks the message as seen_ |\n| ZugferdMailHandlerMarkUnseenMessage | _Marks the message as unseen_ |\n| ZugferdMailHandlerSaveToFile | _Saves the E-Document to a specified directory, optionally with a different filename_ |\n\n### Implement your own handler\n\nIt 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:\n\n```php\npublic function handleDocument(\n    ZugferdMailAccount $account,\n    Folder $folder,\n    Message $message,\n    Attachment $attachment,\n    ZugferdDocumentReader $document,\n    int $recognitionType\n);\n```\n\nAn example:\n\n```php\n\nuse horstoeko\\zugferd\\ZugferdDocumentReader;\nuse horstoeko\\zugferdmail\\config\\ZugferdMailAccount;\nuse Webklex\\PHPIMAP\\Attachment;\nuse Webklex\\PHPIMAP\\Folder;\nuse Webklex\\PHPIMAP\\Message;\n\nclass MyOwnHandler extends ZugferdMailHandlerAbstract\n{\n    public function handleDocument(\n        ZugferdMailAccount $account,\n        Folder $folder,\n        Message $message,\n        Attachment $attachment,\n        ZugferdDocumentReader $document,\n        int $recognitionType)\n    {\n        // Do some stuff\n    }\n}\n```\n\nThe parameter $recognitionType is one of the constants from ```ZugferdMailReaderRecognitionType```\n\n| Name | Vakue | Description |\n| :------ | :------ | :------ |\n| ZFMAIL_RECOGNITION_TYPE_PDF_CII | 0 | The document was recognized from a ZUGFeRD/Factur-X PDF attachment\n| ZFMAIL_RECOGNITION_TYPE_XML_CII | 1 | The document was recognized from a ZUGFeRD/Factur-X XML attachment\n| ZFMAIL_RECOGNITION_TYPE_XML_UBL | 2 | The document was recognized from a ZUGFeRD/Factur-X XML attachment (in UBL-Syntax)\n\n### A small example\n\nA possible implementation could look like this, for example:\n\n```php\nuse Webklex\\PHPIMAP\\Folder;\nuse Webklex\\PHPIMAP\\Message;\nuse Webklex\\PHPIMAP\\Attachment;\nuse horstoeko\\zugferd\\ZugferdDocumentReader;\nuse horstoeko\\zugferdmail\\ZugferdMailReader;\nuse horstoeko\\zugferdmail\\config\\ZugferdMailConfig;\nuse horstoeko\\zugferdmail\\config\\ZugferdMailAccount;\nuse horstoeko\\zugferdmail\\handlers\\ZugferdMailHandlerSaveToFile;\n\nrequire dirname(__FILE__) . \"/../vendor/autoload.php\";\n\n$config = new ZugferdMailConfig();\n\n$account1 = $config-\u003eaddAccount('de', '127.0.0.1', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');\n$account1-\u003eaddFolderToWatch('Accounts/invoice@mydomain.com');\n$account1-\u003eaddMimeTypeToWatch('application/pdf');\n$account1-\u003eaddMimeTypeToWatch('text/xml');\n$account1-\u003eaddHandler(new ZugferdMailHandlerSaveToFile('/tmp', 'file.xml'));\n$account1-\u003eaddCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {\n    $document-\u003egetDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);\n    // Some business logic here...\n});\n\n$account2 = $config-\u003eaddAccount('de', '172.10.10.10', 993, 'imap', 'ssl', false, 'demouser', 'demopassword');\n$account2-\u003eaddFolderToWatch('Accounts/invoice@otheromain.com');\n$account2-\u003eaddMimeTypeToWatch('application/pdf');\n$account2-\u003eaddMimeTypeToWatch('text/xml');\n$account1-\u003eaddCallback(function(ZugferdMailAccount $account, Folder $folder, Message $message, Attachment $attachment, ZugferdDocumentReader $document, int $recognitionType) {\n    $document-\u003egetDocumentInformation($documentno, $documenttypecode, $documentdate, $invoiceCurrency, $taxCurrency, $documentname, $documentlanguage, $effectiveSpecifiedPeriod);\n    // Some other business logic here...\n});\n\n$reader = new ZugferdMailReader($config);\n$reader-\u003echeckAllAccounts();\n```\n\n### Console\n\nThis 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:\n\n```sh\n./vendor/bin/ZugferdMailConsole list\n```\n\n#### Start monitoring a mailbox\n\nThe command ``zfmail:processmailboxfolders`` is available for monitoring a mailbox via shell:\n\n```sh\n./vendor/bin/ZugferdMailConsole zfmail:processmailboxfolders [options]\n```\n\nThis has the following parameters:\n\n| Parameter | Description | Default | Multiple |\n| :-------- | :---------- | :------ | :------: |\n| host | The IP or hostname | | :x: |\n| port | The port on the host | 993 | :x: |\n| protocol | The protocol to use | imap | :x: |\n| encryption | The encryption method to use | ssl | :x: |\n| validateCert | If given the SSL certificates will be validated | false | :x: |\n| username | The username to use for login | | :x: |\n| password | The password to use for login | | :x: |\n| authentication | The authentication method to use | | :x: |\n| timeout | The connection timeout | 30 | :x: |\n| folder | A folder to look into | | :heavy_check_mark: |\n| mimetype | An attachment mimetype to check | | :heavy_check_mark: |\n| handler | A handler to use | | :heavy_check_mark: |\n| enableublsupport | If given the application will check for UBL syntax too | false | :x: |\n| enablesymfonyvalidation | If given the application will validate the XML using symfony validator against the yaml definitions | false | :x: |\n| enablexsdvalidation | If given the application will validate the XML against the XSD definitions | false | :x: |\n| enablekositvalidation | If given the application will validate the XML using the KosIT validator (JAVA required) | false | :x: |\n| enableunseenonly | If given only unseen message are processed | false | :x: |\n\nExample usage\n\n```bash\n./vendor/bin/ZugferdMailConsole zfmail:processmailboxfolders \\\n  --host 127.0.0.1 \\\n  --port 993 \\\n  --username demouser \\\n  --password demopassword \\\n  --folder=INBOX \\\n  --mimetype=application/pdf \\\n  --mimetype=text/xml \\\n  --handler=\"horstoeko\\zugferdmail\\handlers\\ZugferdMailHandlerCli\" \\\n  --handler=\"horstoeko\\zugferdmail\\handlers\\ZugferdMailHandlerSaveToFile,/tmp\" \\\n  --enableublsupport\n```\n\n\n[def]: #imappop3-watcher-for-e-documents","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhorstoeko%2Fzugferdmail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhorstoeko%2Fzugferdmail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhorstoeko%2Fzugferdmail/lists"}