Skip to content

Commit 98a7726

Browse files
arhimedearhimede
authored
Merge pull request #81 from dotkernel/issue-76
added upgrade-v4-to-v5 page
2 parents af97d84 + 6467697 commit 98a7726

File tree

2 files changed

+119
-0
lines changed

2 files changed

+119
-0
lines changed

‎docs/book/v5/upgrade-v4-to-v5.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# How to update `dotkernel/dot-mail` from v3/v4 to v5 in your projects
2+
3+
- The first thing to do is download the new [mail configuration file](https://github.com/dotkernel/dot-mail/blob/5.0/config/mail.global.php.dist).
4+
- Add the values you configured for your project, focusing on `transport`, `message_options` and `smtp_options`, then replace your old configuration file.
5+
- In your `composer.json` update `"dotkernel/dot-mail": "^5.0.0",` and run `composer update` in the command line.
6+
7+
At this moment, `mime` and `imap` related functionality is removed.
8+
9+
## Technical approach
10+
11+
You can follow all the changes in this list of PRs:
12+
13+
- [dot-mail PR 65](https://github.com/dotkernel/dot-mail/pull/65/files)
14+
- [dot-mail PR 66](https://github.com/dotkernel/dot-mail/pull/66/files)
15+
- [dot-mail PR 67](https://github.com/dotkernel/dot-mail/pull/67/files)
16+
- [dot-mail PR 69](https://github.com/dotkernel/dot-mail/pull/69/files)
17+
18+
> Function definition changes will not be covered in this article.
19+
20+
When upgrading dotkernel/dot-mail from v4 to v5, the main focus is on the configuration file `mail.global.php`.
21+
It was revised to implement symfony/mailer, to remove features that are no longer available and to make dotkernel/dot-mail easier to configure.
22+
23+
```php
24+
?php
25+
26+
declare(strict_types=1);
27+
28+
return [
29+
/**
30+
* Dotkernel mail module configuration
31+
* Note that many of these options can be set programmatically too, when sending mail messages actually that is
32+
* what you'll usually do, these configs provide just defaults and options that remain the same for all mails
33+
*/
34+
'dot_mail' => [
35+
//the key is the mail service name, this is the default one, which does not extend any configuration
36+
'default' => [
37+
//message configuration
38+
'message_options' => [
39+
//from email address of the email
40+
'from' => '',
41+
//from name to be displayed instead of from address
42+
'from_name' => '',
43+
//reply-to email address of the email
44+
'reply_to' => '',
45+
//replyTo name to be displayed instead of the address
46+
'reply_to_name' => '',
47+
//destination email address as string or a list of email addresses
48+
'to' => [],
49+
//copy destination addresses
50+
'cc' => [],
51+
//hidden copy destination addresses
52+
'bcc' => [],
53+
//email subject
54+
'subject' => '',
55+
//body options - content can be plain text, HTML
56+
'body' => [
57+
'content' => '',
58+
'charset' => 'utf-8',
59+
],
60+
//attachments config
61+
'attachments' => [
62+
'files' => [],
63+
'dir' => [
64+
'iterate' => false,
65+
'path' => 'data/mail/attachments',
66+
'recursive' => false,
67+
],
68+
],
69+
],
70+
/**
71+
* the mail transport to use can be any class implementing
72+
* Symfony\Component\Mailer\Transport\TransportInterface
73+
*
74+
* for standard mail transports, you can use these aliases:
75+
* - sendmail => Symfony\Component\Mailer\Transport\SendmailTransport
76+
* - esmtp => Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport
77+
*
78+
* defaults to sendmail
79+
**/
80+
'transport' => 'sendmail',
81+
//options that will be used only if esmtp adapter is used
82+
'smtp_options' => [
83+
//hostname or IP address of the mail server
84+
'host' => '',
85+
//port of the mail server - 587 or 465 for secure connections
86+
'port' => 587,
87+
'connection_config' => [
88+
//the smtp authentication identity
89+
'username' => '',
90+
//the smtp authentication credential
91+
'password' => '',
92+
//to disable auto_tls set tls key to false
93+
//it's not recommended to disable TLS while connecting to an SMTP server
94+
'tls' => null,
95+
],
96+
],
97+
],
98+
// option to log the SENT emails
99+
'log' => [
100+
'sent' => getcwd() . '/log/mail/sent.log',
101+
],
102+
],
103+
];
104+
```
105+
106+
Make sure to use **ONE** of the below transporters, based on your server configuration.
107+
108+
```php
109+
'transport' => 'sendmail',
110+
```
111+
112+
OR
113+
114+
```php
115+
'transport' => 'esmtp',
116+
```
117+
118+
We set **Sendmail** to be the default.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ nav:
2020
- Configuration: v5/configuration.md
2121
- Usage: v5/usage.md
2222
- Transports: v5/transports.md
23+
- Upgrade from V4 to v5: v5/upgrade-v4-to-v5.md
2324
site_name: dot-mail
2425
site_description: "Dotkernel's mail service"
2526
repo_url: "https://github.com/dotkernel/dot-mail"

0 commit comments

Comments
 (0)