|
| 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. |
0 commit comments