What prompted the change

According to the discussion from the LaminasTechnical steering Committee of 2023-12-04, it was decided that the laminas/laminas-mail package would be abandoned. On the one hand, there is nobody to maintain the package and on the other, there are several alternatives available in the ecosystem:

• ddeboer/imap for interacting with IMAP
• zbateson/mail-mime-parser for parsing MIME messages
• symfony/mailer for sending mail

How Dotkernel handles the issue

The Dotkernel team has also opted to replace the laminas/laminas-mail package in the dotkernel/dot-mail package. This meant revising the code, including the configuraton files. The optimal way to handle this was to try to have minimal impact on existing projects that already use dotkernel/dot-mail. This means that the calls to send the mail should remain the same, even if some lesser-used functionality like mime and imap are lost.

Technical approach

In this article we will list the edits that enabled the switch from laminas/laminas-mail to symfony/mailer in the dotkernel/dot-mail package. You can follow all the changes in this list of PRs:

• dot-mail PR 65
• dot-mail PR 66
• dot-mail PR 67
• dot-mail PR 69

Function definition changes will not be covered in this article.

The configuration file mail.global.php was revised to remove features that are no longer available and to make it easier to configure.

?php

declare(strict_types=1);

return [
    /**
     * Dotkernel mail module configuration
     * Note that many of these options can be set programmatically too, when sending mail messages actually that is
     * what you'll usually do, these configs provide just defaults and options that remain the same for all mails
     */
    'dot_mail' => [
        //the key is the mail service name, this is the default one, which does not extend any configuration
        'default' => [
            //message configuration
            'message_options' => [
                //from email address of the email
                'from' => '',
                //from name to be displayed instead of from address
                'from_name' => '',
                //reply-to email address of the email
                'reply_to' => '',
                //replyTo name to be displayed instead of the address
                'reply_to_name' => '',
                //destination email address as string or a list of email addresses
                'to' => [],
                //copy destination addresses
                'cc' => [],
                //hidden copy destination addresses
                'bcc' => [],
                //email subject
                'subject' => '',
                //body options - content can be plain text, HTML
                'body' => [
                    'content' => '',
                    'charset' => 'utf-8',
                ],
                //attachments config
                'attachments' => [
                    'files' => [],
                    'dir'   => [
                        'iterate'   => false,
                        'path'      => 'data/mail/attachments',
                        'recursive' => false,
                    ],
                ],
            ],
            /**
             * the mail transport to use can be any class implementing
             * Symfony\Component\Mailer\Transport\TransportInterface
             *
             * for standard mail transports, you can use these aliases:
             * - sendmail  => Symfony\Component\Mailer\Transport\SendmailTransport
             * - esmtp     => Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport
             *
             * defaults to sendmail
             **/
            'transport' => 'sendmail',
            //options that will be used only if esmtp adapter is used
            'smtp_options' => [
                //hostname or IP address of the mail server
                'host' => '',
                //port of the mail server - 587 or 465 for secure connections
                'port'              => 587,
                'connection_config' => [
                    //the smtp authentication identity
                    'username' => '',
                    //the smtp authentication credential
                    'password' => '',
                    //to disable auto_tls set tls key to false
                    //it's not recommended to disable TLS while connecting to an SMTP server
                    'tls' => null,
                ],
            ],
        ],
        // option to log the SENT emails
        'log' => [
            'sent' => getcwd() . '/log/mail/sent.log',
        ],
    ],
];

Make sure to use ONE of the below transporters, based on your server configuration.

'transport' => 'sendmail',

OR

'transport' => 'esmtp',

We set Sendmail to be the default mail transport.

How to update dotkernel/dot-mail from version 3 or version 4 to version 5 in your projects

• The first thing to do is download the new mail configuration file.
• Add the values you configured for your project, focusing on transport, message_options and smtp_options, then replace your old configuration file.
• In your composer.json update "dotkernel/dot-mail": "^5.0.0", and run composer update in the command line.

At this moment, mime and imap related functionality is removed.

---