Merge pull request #41 from dotkernel/issue-24b

updated storage code, readme

Author: bidi47

CHANGELOG.md

@@ -1,3 +1,21 @@
+## 4.0.3 - 2022-08-31
+
+### Changed
+* Improved email storage handling
+* Updated readme
+
+### Added
+* Nothing
+
+### Deprecated
+* Nothing
+
+### Removed
+* Nothing
+
+### Fixed
+* Nothing
+
 ## 4.0.2 - 2022-08-23
 
 ### Changed
@@ -51,6 +69,91 @@
 ### Fixed
 * Nothing
 
+## 3.4.5 - 2022-08-30
+
+### Changed
+* Updated readme
+
+### Added
+* Nothing
+
+### Deprecated
+* Nothing
+
+### Removed
+* Nothing
+
+### Fixed
+* Nothing
+
+## 3.4.4 - 2022-08-26
+
+### Changed
+* Nothing
+
+### Added
+* Nothing
+
+### Deprecated
+* Nothing
+
+### Removed
+* Nothing
+
+### Fixed
+* Updated check for storage
+
+## 3.4.3 - 2022-08-25
+
+### Changed
+* Improved email storage handling
+
+### Added
+* Nothing
+
+### Deprecated
+* Nothing
+
+### Removed
+* Nothing
+
+### Fixed
+* Nothing
+
+## 3.4.2 - 2022-08-23
+
+### Changed
+* Updated mail.global.php.dist
+
+### Added
+* Nothing
+
+### Deprecated
+* Nothing
+
+### Removed
+* Nothing
+
+### Fixed
+* Nothing
+
+## 3.4.1 - 2022-08-12
+
+### Changed
+* Nothing
+
+### Added
+* Nothing
+
+### Deprecated
+* Nothing
+
+### Removed
+* laminas/laminas-dependency-plugin
+
+### Fixed
+* Nothing
+
 ## 3.4.0 - 2022-08-10
 
 ### Changed

README.md

@@ -11,7 +11,100 @@ DotKernel mail component based on [laminas-mail](https://github.com/laminas/lami
 [![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/stargazers)
 [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/blob/4.0/LICENSE.md)
 
+### Configuration
 
+#### Mail - Sendmail
+If your server has Sendmail installed, update the `config/autoload/mail.local.php.dist` file by setting the `transport` key like below
+
+```php
+<?php
+return [
+    'dot_mail' => [
+        'default' => [
+            //...
+            'transport' => Laminas\Mail\Transport\Sendmail::class,
+            //...
+        ]
+    ]
+]
+```
+
+#### Mail - SMTP
+If you want your application to send mails on e.g. registration, contact, then edit the file `config/autoload/mail.local.php`.  Set the `transport`, `message_options` and `smtp_options` keys like below.
+
+Under `message_options` key:
+- `from` - email address from whom users will receive emails
+
+Under `smtp_options` key:
+- `host` - the mail server's hostname or IP address
+- `port` - the mail server's port
+- `connection_config` - fill in the `username`, `password` and `ssl` keys with the login details of the email used in `from` above
+
+Note: all other keys can be left as is.
+
+```php
+<?php
+return [
+    'dot_mail' => [
+        'default' => [
+            //...
+            'transport' => Laminas\Mail\Transport\Smtp::class,
+            'message_options' => [
+                'from' => '',
+                //...
+            ],
+            'smtp_options' => [
+                'host' => '',
+                'port' => 25,
+                'connection_config' => [
+                    'username' => '',
+                    'password' => '',
+                    'ssl' => '',
+                ]
+            ]
+            //...
+        ]
+    ]
+]
+```
+
+In `config/autoload/local.php` add under `contact` => `message_receivers` => `to` key *string* values with the emails that should receive contact messages
+
+Note: **Please add at least 1 email address in order for contact message to reach someone**
+
+Also feel free to add as many cc as you want under `contact` => `message_receivers` => `cc` key
+
+### Sending an e-mail
+
+Below is an example of how to use the email in the most basic way. You can add your own code to it e.g. to get the user data from a User object or from a config file, to use a template for the body.
+
+Note that `addTo` is only one of the methods available for the `Message` class returned by `getMessage()`. Other useful methods that were not included in the example are `addCc()`, `addBcc()`, `addReplyTo()`.
+
+The returned type is boolean, but if the `isValid()` method is removed, the returned type becomes `MailResult` which allows the use of `getMessage()` for a more detailed error message. See the `Testing if an e-mail message is valid` section below.
+
+```php
+public function sendBasicMail()
+{
+    $this->mailService->setBody('Email body');
+    $this->mailService->setSubject('Email subject');
+    $this->mailService->getMessage()->addTo('email@example.com', 'User name');
+    $this->mailService->getMessage()->setEncoding('utf-8');
+    return $this->mailService->send()->isValid();
+}
+```
+
+It's optional, but recommended to call the above function in a `try-catch` block to display helpful error messages. The next example calls the `sendBasicMail` function from within `UserController`, but you can implement it in other controllers, just make sure that the controller's construct also includes the `FlashMessenger` parameter `$messenger`.
+
+```php
+try {
+    $this->userService->sendBasicMail();
+    $this->messenger->addSuccess('The mail was sent successfully', 'user-login');
+    //more code...
+} catch (Exception $exception) {
+    $this->messenger->addError($exception->getMessage(), 'user-login');
+    //more code...
+}
+```
 
 ### Testing if an e-mail message is valid
 After sending an e-mail you can check if the message was valid or not.

mail.global.php.dist

@@ -130,6 +130,10 @@ return [
                 //],
             ],
         ],
+        // option to log the SENT emails
+        'log' => [
+          'sent' => getcwd() . '/log/mail/sent.log'
+        ],
 
         /**
          * You can define other mail services here, with the same structure as the default block

src/Factory/MailServiceAbstractFactory.php

@@ -19,7 +19,6 @@
 use Dot\Mail\Service\MailServiceInterface;
 use Interop\Container\ContainerInterface;
 use Laminas\Mail\Message;
-use Laminas\Mail\Storage\Imap;
 use Laminas\Mail\Transport\File;
 use Laminas\Mail\Transport\Smtp;
 use Laminas\Mail\Transport\TransportInterface;
@@ -59,9 +58,8 @@ public function __invoke(
         $logService = $container->get(LogServiceInterface::class);
         $message = $this->createMessage();
         $transport = $this->createTransport($container);
-        $storage = $this->createStorage($container);
 
-        $mailService = new MailService($logService, $message, $transport, $storage, $this->mailOptions);
+        $mailService = new MailService($logService, $message, $transport, $this->mailOptions);
 
         //set subject
         $mailService->setSubject($this->mailOptions->getMessageOptions()->getSubject());
@@ -188,23 +186,6 @@ protected function setupTransportConfig(TransportInterface $transport)
         return $transport;
     }
 
-    /**
-     * @param ContainerInterface $container
-     * @return Imap
-     */
-    protected function createStorage(ContainerInterface $container)
-    {
-        $host = $this->mailOptions->getSmtpOptions()->getHost();
-        $connectionConfig = $this->mailOptions->getSmtpOptions()->getConnectionConfig();
-        $storage = new Imap([
-                                'host'     => $host,
-                                'user'     => $connectionConfig['username'],
-                                'password' => $connectionConfig['password'],
-                            ]);
-
-        return $storage;
-    }
-
     /**
      * @param MailEventListenerAwareInterface $service
      * @param ContainerInterface $container

src/Service/MailService.php

@@ -40,25 +40,26 @@ class MailService implements
 
     protected TransportInterface $transport;
 
+    protected MailOptions $mailOptions;
+
     protected array $attachments = [];
 
     /**
      * MailService constructor.
      * @param LogServiceInterface $logService
      * @param Message $message
      * @param TransportInterface $transport
+     * @param MailOptions $mailOptions
      */
     public function __construct(
         LogServiceInterface $logService,
         Message $message,
         TransportInterface $transport,
-        Imap $storage,
         MailOptions $mailOptions
     ) {
         $this->logService = $logService;
         $this->message = $message;
         $this->transport = $transport;
-        $this->storage = $storage;
         $this->mailOptions = $mailOptions;
     }
 
@@ -94,15 +95,40 @@ public function send(): ResultInterface
         }
 
         //save copy of sent message to folders
-        if ($this->mailOptions->getSaveSentMessageFolder()) {
-            foreach ($this->mailOptions->getSaveSentMessageFolder() as $folder) {
-                $this->storage->appendMessage($this->message->toString(), $folder);
+        if ($this->mailOptions->getTransport() == \Laminas\Mail\Transport\Smtp::class &&
+            $this->mailOptions->getSaveSentMessageFolder()) {
+            $this->storage = $this->createStorage();
+            if ($this->storage) {
+                foreach ($this->mailOptions->getSaveSentMessageFolder() as $folder) {
+                    $this->storage->appendMessage($this->message->toString(), $folder);
+                }
             }
         }
 
         return $result;
     }
 
+    /**
+     * @return Imap|null
+     */
+    protected function createStorage(): ?Imap
+    {
+        $host = $this->mailOptions->getSmtpOptions()->getHost();
+        if (empty($host)) {
+            return null;
+        }
+        $connectionConfig = $this->mailOptions->getSmtpOptions()->getConnectionConfig();
+        if (empty($connectionConfig['username']) || empty($connectionConfig['password'])) {
+            return null;
+        }
+
+        return new Imap([
+                            'host'     => $host,
+                            'user'     => $connectionConfig['username'],
+                            'password' => $connectionConfig['password'],
+                        ]);
+    }
+
     /**
      * @param string $name
      * @param ResultInterface|null $result
@@ -283,10 +309,14 @@ public function setTransport(TransportInterface $transport)
     }
 
     /**
-     * @return array
+     * @return array|false
      */
     public function getFolderGlobalNames()
     {
+        $this->storage = $this->createStorage();
+        if (!$this->storage) {
+            return false;
+        }
         $folderGlobalNames = [];
         foreach ($this->storage->getFolders() as $folder) {
             $folderGlobalNames[] = $folder->getGlobalName();