Skip to content

Commit af138e2

Browse files
author
bidi
committed
updated storage code, readme
1 parent 3630d56 commit af138e2

5 files changed

Lines changed: 237 additions & 26 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
## 4.0.3 - 2022-08-31
2+
3+
### Changed
4+
* Improved email storage handling
5+
* Updated readme
6+
7+
### Added
8+
* Nothing
9+
10+
### Deprecated
11+
* Nothing
12+
13+
### Removed
14+
* Nothing
15+
16+
### Fixed
17+
* Nothing
18+
119
## 4.0.2 - 2022-08-23
220

321
### Changed
@@ -51,6 +69,91 @@
5169
### Fixed
5270
* Nothing
5371

72+
## 3.4.5 - 2022-08-30
73+
74+
### Changed
75+
* Updated readme
76+
77+
### Added
78+
* Nothing
79+
80+
### Deprecated
81+
* Nothing
82+
83+
### Removed
84+
* Nothing
85+
86+
### Fixed
87+
* Nothing
88+
89+
## 3.4.4 - 2022-08-26
90+
91+
### Changed
92+
* Nothing
93+
94+
### Added
95+
* Nothing
96+
97+
### Deprecated
98+
* Nothing
99+
100+
### Removed
101+
* Nothing
102+
103+
### Fixed
104+
* Updated check for storage
105+
106+
## 3.4.3 - 2022-08-25
107+
108+
### Changed
109+
* Improved email storage handling
110+
111+
### Added
112+
* Nothing
113+
114+
### Deprecated
115+
* Nothing
116+
117+
### Removed
118+
* Nothing
119+
120+
### Fixed
121+
* Nothing
122+
123+
## 3.4.2 - 2022-08-23
124+
125+
### Changed
126+
* Updated mail.global.php.dist
127+
128+
### Added
129+
* Nothing
130+
131+
### Deprecated
132+
* Nothing
133+
134+
### Removed
135+
* Nothing
136+
137+
### Fixed
138+
* Nothing
139+
140+
## 3.4.1 - 2022-08-12
141+
142+
### Changed
143+
* Nothing
144+
145+
### Added
146+
* Nothing
147+
148+
### Deprecated
149+
* Nothing
150+
151+
### Removed
152+
* laminas/laminas-dependency-plugin
153+
154+
### Fixed
155+
* Nothing
156+
54157
## 3.4.0 - 2022-08-10
55158

56159
### Changed

‎README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,100 @@ DotKernel mail component based on [laminas-mail](https://github.com/laminas/lami
1111
[![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/stargazers)
1212
[![GitHub license](https://img.shields.io/github/license/dotkernel/dot-mail)](https://github.com/dotkernel/dot-mail/blob/4.0/LICENSE.md)
1313

14+
### Configuration
1415

16+
#### Mail - Sendmail
17+
If your server has Sendmail installed, update the `config/autoload/mail.local.php.dist` file by setting the `transport` key like below
18+
19+
```php
20+
<?php
21+
return [
22+
'dot_mail' => [
23+
'default' => [
24+
//...
25+
'transport' => Laminas\Mail\Transport\Sendmail::class,
26+
//...
27+
]
28+
]
29+
]
30+
```
31+
32+
#### Mail - SMTP
33+
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.
34+
35+
Under `message_options` key:
36+
- `from` - email address from whom users will receive emails
37+
38+
Under `smtp_options` key:
39+
- `host` - the mail server's hostname or IP address
40+
- `port` - the mail server's port
41+
- `connection_config` - fill in the `username`, `password` and `ssl` keys with the login details of the email used in `from` above
42+
43+
Note: all other keys can be left as is.
44+
45+
```php
46+
<?php
47+
return [
48+
'dot_mail' => [
49+
'default' => [
50+
//...
51+
'transport' => Laminas\Mail\Transport\Smtp::class,
52+
'message_options' => [
53+
'from' => '',
54+
//...
55+
],
56+
'smtp_options' => [
57+
'host' => '',
58+
'port' => 25,
59+
'connection_config' => [
60+
'username' => '',
61+
'password' => '',
62+
'ssl' => '',
63+
]
64+
]
65+
//...
66+
]
67+
]
68+
]
69+
```
70+
71+
In `config/autoload/local.php` add under `contact` => `message_receivers` => `to` key *string* values with the emails that should receive contact messages
72+
73+
Note: **Please add at least 1 email address in order for contact message to reach someone**
74+
75+
Also feel free to add as many cc as you want under `contact` => `message_receivers` => `cc` key
76+
77+
### Sending an e-mail
78+
79+
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.
80+
81+
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()`.
82+
83+
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.
84+
85+
```php
86+
public function sendBasicMail()
87+
{
88+
$this->mailService->setBody('Email body');
89+
$this->mailService->setSubject('Email subject');
90+
$this->mailService->getMessage()->addTo('email@example.com', 'User name');
91+
$this->mailService->getMessage()->setEncoding('utf-8');
92+
return $this->mailService->send()->isValid();
93+
}
94+
```
95+
96+
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`.
97+
98+
```php
99+
try {
100+
$this->userService->sendBasicMail();
101+
$this->messenger->addSuccess('The mail was sent successfully', 'user-login');
102+
//more code...
103+
} catch (Exception $exception) {
104+
$this->messenger->addError($exception->getMessage(), 'user-login');
105+
//more code...
106+
}
107+
```
15108

16109
### Testing if an e-mail message is valid
17110
After sending an e-mail you can check if the message was valid or not.

‎mail.global.php.dist‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,10 @@ return [
126126
//],
127127
],
128128
],
129+
// option to log the SENT emails
130+
'log' => [
131+
'sent' => getcwd() . '/log/mail/sent.log'
132+
],
129133

130134
/**
131135
* You can define other mail services here, with the same structure as the default block

‎src/Factory/MailServiceAbstractFactory.php‎

Lines changed: 1 addition & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@
1919
use Dot\Mail\Service\MailServiceInterface;
2020
use Interop\Container\ContainerInterface;
2121
use Laminas\Mail\Message;
22-
use Laminas\Mail\Storage\Imap;
2322
use Laminas\Mail\Transport\File;
2423
use Laminas\Mail\Transport\Smtp;
2524
use Laminas\Mail\Transport\TransportInterface;
@@ -59,9 +58,8 @@ public function __invoke(
5958
$logService = $container->get(LogServiceInterface::class);
6059
$message = $this->createMessage();
6160
$transport = $this->createTransport($container);
62-
$storage = $this->createStorage($container);
6361

64-
$mailService = new MailService($logService, $message, $transport, $storage, $this->mailOptions);
62+
$mailService = new MailService($logService, $message, $transport, $this->mailOptions);
6563

6664
//set subject
6765
$mailService->setSubject($this->mailOptions->getMessageOptions()->getSubject());
@@ -188,23 +186,6 @@ protected function setupTransportConfig(TransportInterface $transport)
188186
return $transport;
189187
}
190188

191-
/**
192-
* @param ContainerInterface $container
193-
* @return Imap
194-
*/
195-
protected function createStorage(ContainerInterface $container)
196-
{
197-
$host = $this->mailOptions->getSmtpOptions()->getHost();
198-
$connectionConfig = $this->mailOptions->getSmtpOptions()->getConnectionConfig();
199-
$storage = new Imap([
200-
'host' => $host,
201-
'user' => $connectionConfig['username'],
202-
'password' => $connectionConfig['password'],
203-
]);
204-
205-
return $storage;
206-
}
207-
208189
/**
209190
* @param MailEventListenerAwareInterface $service
210191
* @param ContainerInterface $container

‎src/Service/MailService.php‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,25 +40,26 @@ class MailService implements
4040

4141
protected TransportInterface $transport;
4242

43+
protected MailOptions $mailOptions;
44+
4345
protected array $attachments = [];
4446

4547
/**
4648
* MailService constructor.
4749
* @param LogServiceInterface $logService
4850
* @param Message $message
4951
* @param TransportInterface $transport
52+
* @param MailOptions $mailOptions
5053
*/
5154
public function __construct(
5255
LogServiceInterface $logService,
5356
Message $message,
5457
TransportInterface $transport,
55-
Imap $storage,
5658
MailOptions $mailOptions
5759
) {
5860
$this->logService = $logService;
5961
$this->message = $message;
6062
$this->transport = $transport;
61-
$this->storage = $storage;
6263
$this->mailOptions = $mailOptions;
6364
}
6465

@@ -94,15 +95,40 @@ public function send(): ResultInterface
9495
}
9596

9697
//save copy of sent message to folders
97-
if ($this->mailOptions->getSaveSentMessageFolder()) {
98-
foreach ($this->mailOptions->getSaveSentMessageFolder() as $folder) {
99-
$this->storage->appendMessage($this->message->toString(), $folder);
98+
if ($this->mailOptions->getTransport() == \Laminas\Mail\Transport\Smtp::class &&
99+
$this->mailOptions->getSaveSentMessageFolder()) {
100+
$this->storage = $this->createStorage();
101+
if ($this->storage) {
102+
foreach ($this->mailOptions->getSaveSentMessageFolder() as $folder) {
103+
$this->storage->appendMessage($this->message->toString(), $folder);
104+
}
100105
}
101106
}
102107

103108
return $result;
104109
}
105110

111+
/**
112+
* @return Imap|null
113+
*/
114+
protected function createStorage(): ?Imap
115+
{
116+
$host = $this->mailOptions->getSmtpOptions()->getHost();
117+
if (empty($host)) {
118+
return null;
119+
}
120+
$connectionConfig = $this->mailOptions->getSmtpOptions()->getConnectionConfig();
121+
if (empty($connectionConfig['username']) || empty($connectionConfig['password'])) {
122+
return null;
123+
}
124+
125+
return new Imap([
126+
'host' => $host,
127+
'user' => $connectionConfig['username'],
128+
'password' => $connectionConfig['password'],
129+
]);
130+
}
131+
106132
/**
107133
* @param string $name
108134
* @param ResultInterface|null $result
@@ -283,10 +309,14 @@ public function setTransport(TransportInterface $transport)
283309
}
284310

285311
/**
286-
* @return array
312+
* @return array|false
287313
*/
288314
public function getFolderGlobalNames()
289315
{
316+
$this->storage = $this->createStorage();
317+
if (!$this->storage) {
318+
return false;
319+
}
290320
$folderGlobalNames = [];
291321
foreach ($this->storage->getFolders() as $folder) {
292322
$folderGlobalNames[] = $folder->getGlobalName();

0 commit comments

Comments
 (0)