From f86a9fa48e51b288e8002fe4a73fb10bcf3961be Mon Sep 17 00:00:00 2001 From: Milan Sulc Date: Thu, 4 Jun 2026 20:30:50 +0000 Subject: [PATCH 1/2] Docs: move documentation to README --- .docs/README.md | 252 ----------------------------------------------- README.md | 257 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 248 insertions(+), 261 deletions(-) delete mode 100644 .docs/README.md diff --git a/.docs/README.md b/.docs/README.md deleted file mode 100644 index 0ac5bd9..0000000 --- a/.docs/README.md +++ /dev/null @@ -1,252 +0,0 @@ -# Contributte Mail - -Extra contribution to [`nette/mail`](https://github.com/nette/mail). - -## Content - -- [Setup](#setup) -- [Configuration](#configuration) -- [Mailers](#mailers) - - [FileMailer](#filemailer) - - [SendmailMailer](#sendmailmailer) - - [DevOpsMailer](#devopsmailer) - - [CompositeMailer](#compositemailer) - - [DevNullMailer](#devnullmailer) - - [TraceableMailer](#traceablemailer) -- [Message](#message) -- [IMAP](#imap) - -## Setup - -Install package - -```bash -composer require contributte/mail -``` - -Register extension - -```neon -extensions: - # Native nette/mail - mail: Nette\Bridges\MailDI\MailExtension - - # Our contributte/mail - post: Contributte\Mail\DI\MailExtension -``` - -## Configuration - -You have to manually register this extension in the first place. - -Be careful, `nette/mail` is registered by default under the `mail` key, that's why we have picked the `post` key. - -Simple example: - -```neon -extensions: - mail: Nette\Bridges\MailDI\MailExtension - post: Contributte\Mail\DI\MailExtension -``` - -## Mailers - -### FileMailer - -Stores emails on your file system. - -**Configuration** - -```neon -services: - # Dump mails in folder - mail.mailer: Contributte\Mail\Mailer\FileMailer(%tempDir%/mails) -``` - -```php -$mailer = new FileMailer(__DIR__ . '/temp/mails'); -``` - -### SendmailMailer - -This is the default `Nette\Mail\SendmailMailer` with some extra methods and fields. - -**Configuration** - -```neon -services: - # Polished sendmail - mail.mailer: - class: Contributte\Mail\Mailer\SendmailMailer - setup: - - setBounceMail(mail@contributte.org) -``` - -**Bounce mail** - -```php -$mailer->setBounceMail('mail@contributte.org'); -``` - -**Events** - -```php -$mailer->onSend[] = function($mailer, $message) {}; -``` - -### DevOpsMailer - -Sends all emails to one address with preserved original attributes. - -**Configuration** - -```neon -services: - # Redirect all mails to one address - mail.mailer: Contributte\Mail\Mailer\DevOpsMailer(@originalMailer, dev@contributte.org) -``` - -```php -$mailer = new DevOpsMailer($originalMailer, 'dev@contributte.org'); -``` - -### DevNullMailer - -Does literally nothing. - -```php -$mailer = new DevNullMailer(); -``` - -### CompositeMailer - -Combines more mailers together. - -**Configuration** - -```neon -services: - # Send mails to multiple mailers - mail.mailer: - class: Contributte\Mail\Mailer\CompositeMailer - arguments: [silent: false] # If silent is enabled then exceptions from mailers are catched - setup: - - add(@mailer1) - - add(@mailer2) -``` - -```php -$mailer = new CompositeMailer($silent = false); // If silent is enabled then exceptions from mailers are caught -$mailer->add(new FileMailer(__DIR__ . '/temp/mails')); -$mailer->add(new DevOpsMailer('dev@contributte.org')); -``` - -### TraceableMailer - -Internally wraps your mailer and displays sent mails when the `trace` option is set to `true` in a Tracy panel. - -```neon -post: - # Trace emails in Tracy - trace: %debugMode% -``` - -## Message - -### MessageFactory - -You can rely on `IMessageFactory` message factory for creating mail messages. - -```php -use Contributte\Mail\Message\IMessageFactory; - -class Foo -{ - - /** @inject */ - public IMessageFactory $messageFactory; - - public function sendMail(): void - { - $message = $this->messageFactory->create(); - //... - } - -} -``` - -### Message - -`Message` extends `Nette\Mail\Message` and add more functions. - -#### `$message->addTos(array $tos)` - -Accepts an array of recipients and calls `addTo` on each one of them. - -## IMAP - -### ImapReader - -Reads emails from an IMAP mailbox. - -```php -use Contributte\Mail\Imap\ImapReader; - -$reader = new ImapReader('{imap.example.com:993/imap/ssl}INBOX', 'username', 'password'); - -// Read all messages -$messages = $reader->read(); - -// Read unread messages only -$messages = $reader->read(ImapReader::CRITERIA_UNSEEN); - -// Flag message as seen -$reader->flag('1', ImapMessage::FLAG_SEEN); - -// Unflag message -$reader->unflag('1', ImapMessage::FLAG_SEEN); - -// Check connection -if ($reader->isAlive()) { - // Connection is active -} -``` - -### ImapMessage - -Represents an email message retrieved via IMAP. - -```php -use Contributte\Mail\Imap\ImapMessage; - -// Get message properties -$number = $message->getNumber(); -$headers = $message->getHeaders(); -$structure = $message->getStructure(); - -// Get message body -$body = $message->getBody(); -$section = $message->getBodySection(0); -$text = $message->getBodySectionText(0); // UTF-8 converted - -// Get charset -$charset = $message->getBodyCharset(); -``` - -**Message flags:** - -- `ImapMessage::FLAG_SEEN` -- `ImapMessage::FLAG_ANSWERED` -- `ImapMessage::FLAG_FLAGGED` -- `ImapMessage::FLAG_DELETED` -- `ImapMessage::FLAG_DRAFT` - -**Search criteria:** - -- `ImapReader::CRITERIA_ALL` -- `ImapReader::CRITERIA_UNSEEN` -- `ImapReader::CRITERIA_SEEN` -- `ImapReader::CRITERIA_NEW` -- `ImapReader::CRITERIA_FROM` -- `ImapReader::CRITERIA_SUBJECT` -- ... and more diff --git a/README.md b/README.md index af4e2e2..6eb963e 100644 --- a/README.md +++ b/README.md @@ -18,24 +18,263 @@ Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

-## Usage +Extra contrib to nette/mail. -To install latest version of `contributte/mail` use [Composer](https://getcomposer.org). +## Versions + +| State | Version | Branch | Nette | PHP | +|-------------|---------|----------|-------|---------| +| dev | `^0.9` | `master` | 4.0+ | `>=8.1` | +| stable | `^0.8` | `master` | 4.0+ | `>=8.1` | + +## Contents + +- [Installation](#installation) +- [Configuration](#configuration) +- [Mailers](#mailers) + - [FileMailer](#filemailer) + - [SendmailMailer](#sendmailmailer) + - [DevOpsMailer](#devopsmailer) + - [CompositeMailer](#compositemailer) + - [DevNullMailer](#devnullmailer) + - [TraceableMailer](#traceablemailer) +- [Message](#message) +- [IMAP](#imap) + +## Installation + +Install package ```bash composer require contributte/mail ``` -## Documentation +Register extension -For details on how to use this package, check out our [documentation](.docs). +```neon +extensions: + # Native nette/mail + mail: Nette\Bridges\MailDI\MailExtension -## Versions + # Our contributte/mail + post: Contributte\Mail\DI\MailExtension +``` -| State | Version | Branch | Nette | PHP | -|-------------|---------|----------|-------|---------| -| dev | `^0.9` | `master` | 4.0+ | `>=8.1` | -| stable | `^0.8` | `master` | 4.0+ | `>=8.1` | +## Configuration + +You have to manually register this extension in the first place. + +Be careful, `nette/mail` is registered by default under the `mail` key, that's why we have picked the `post` key. + +Simple example: + +```neon +extensions: + mail: Nette\Bridges\MailDI\MailExtension + post: Contributte\Mail\DI\MailExtension +``` + +## Mailers + +### FileMailer + +Stores emails on your file system. + +**Configuration** + +```neon +services: + # Dump mails in folder + mail.mailer: Contributte\Mail\Mailer\FileMailer(%tempDir%/mails) +``` + +```php +$mailer = new FileMailer(__DIR__ . '/temp/mails'); +``` + +### SendmailMailer + +This is the default `Nette\Mail\SendmailMailer` with some extra methods and fields. + +**Configuration** + +```neon +services: + # Polished sendmail + mail.mailer: + class: Contributte\Mail\Mailer\SendmailMailer + setup: + - setBounceMail(mail@contributte.org) +``` + +**Bounce mail** + +```php +$mailer->setBounceMail('mail@contributte.org'); +``` + +**Events** + +```php +$mailer->onSend[] = function($mailer, $message) {}; +``` + +### DevOpsMailer + +Sends all emails to one address with preserved original attributes. + +**Configuration** + +```neon +services: + # Redirect all mails to one address + mail.mailer: Contributte\Mail\Mailer\DevOpsMailer(@originalMailer, dev@contributte.org) +``` + +```php +$mailer = new DevOpsMailer($originalMailer, 'dev@contributte.org'); +``` + +### DevNullMailer + +Does literally nothing. + +```php +$mailer = new DevNullMailer(); +``` + +### CompositeMailer + +Combines more mailers together. + +**Configuration** + +```neon +services: + # Send mails to multiple mailers + mail.mailer: + class: Contributte\Mail\Mailer\CompositeMailer + arguments: [silent: false] # If silent is enabled then exceptions from mailers are catched + setup: + - add(@mailer1) + - add(@mailer2) +``` + +```php +$mailer = new CompositeMailer($silent = false); // If silent is enabled then exceptions from mailers are caught +$mailer->add(new FileMailer(__DIR__ . '/temp/mails')); +$mailer->add(new DevOpsMailer('dev@contributte.org')); +``` + +### TraceableMailer + +Internally wraps your mailer and displays sent mails when the `trace` option is set to `true` in a Tracy panel. + +```neon +post: + # Trace emails in Tracy + trace: %debugMode% +``` + +## Message + +### MessageFactory + +You can rely on `IMessageFactory` message factory for creating mail messages. + +```php +use Contributte\Mail\Message\IMessageFactory; + +class Foo +{ + + /** @inject */ + public IMessageFactory $messageFactory; + + public function sendMail(): void + { + $message = $this->messageFactory->create(); + //... + } + +} +``` + +### Message + +`Message` extends `Nette\Mail\Message` and add more functions. + +#### `$message->addTos(array $tos)` + +Accepts an array of recipients and calls `addTo` on each one of them. + +## IMAP + +### ImapReader + +Reads emails from an IMAP mailbox. + +```php +use Contributte\Mail\Imap\ImapReader; + +$reader = new ImapReader('{imap.example.com:993/imap/ssl}INBOX', 'username', 'password'); + +// Read all messages +$messages = $reader->read(); + +// Read unread messages only +$messages = $reader->read(ImapReader::CRITERIA_UNSEEN); + +// Flag message as seen +$reader->flag('1', ImapMessage::FLAG_SEEN); + +// Unflag message +$reader->unflag('1', ImapMessage::FLAG_SEEN); + +// Check connection +if ($reader->isAlive()) { + // Connection is active +} +``` + +### ImapMessage + +Represents an email message retrieved via IMAP. + +```php +use Contributte\Mail\Imap\ImapMessage; + +// Get message properties +$number = $message->getNumber(); +$headers = $message->getHeaders(); +$structure = $message->getStructure(); + +// Get message body +$body = $message->getBody(); +$section = $message->getBodySection(0); +$text = $message->getBodySectionText(0); // UTF-8 converted + +// Get charset +$charset = $message->getBodyCharset(); +``` + +**Message flags:** + +- `ImapMessage::FLAG_SEEN` +- `ImapMessage::FLAG_ANSWERED` +- `ImapMessage::FLAG_FLAGGED` +- `ImapMessage::FLAG_DELETED` +- `ImapMessage::FLAG_DRAFT` + +**Search criteria:** + +- `ImapReader::CRITERIA_ALL` +- `ImapReader::CRITERIA_UNSEEN` +- `ImapReader::CRITERIA_SEEN` +- `ImapReader::CRITERIA_NEW` +- `ImapReader::CRITERIA_FROM` +- `ImapReader::CRITERIA_SUBJECT` +- ... and more ## Development From 30b2840adc2c18edf2ac62450e37f97378c6cc6f Mon Sep 17 00:00:00 2001 From: Oh My Felix Date: Tue, 7 Jul 2026 17:04:40 +0000 Subject: [PATCH 2/2] Docs: polish README migration --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 6eb963e..767f9c4 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

-Extra contrib to nette/mail. +Additional mail utilities for Nette applications built on top of `nette/mail`. ## Versions @@ -38,7 +38,7 @@ Extra contrib to nette/mail. - [CompositeMailer](#compositemailer) - [DevNullMailer](#devnullmailer) - [TraceableMailer](#traceablemailer) -- [Message](#message) +- [Messages](#messages) - [IMAP](#imap) ## Installation @@ -154,7 +154,7 @@ services: # Send mails to multiple mailers mail.mailer: class: Contributte\Mail\Mailer\CompositeMailer - arguments: [silent: false] # If silent is enabled then exceptions from mailers are catched + arguments: [silent: false] # If silent is enabled then exceptions from mailers are caught setup: - add(@mailer1) - add(@mailer2) @@ -176,7 +176,7 @@ post: trace: %debugMode% ``` -## Message +## Messages ### MessageFactory @@ -200,9 +200,9 @@ class Foo } ``` -### Message +### Extended Message -`Message` extends `Nette\Mail\Message` and add more functions. +`Message` extends `Nette\Mail\Message` and adds more functions. #### `$message->addTos(array $tos)`