README

Yii Mailer Library - Symfony Mailer Extension

This extension provides a Symfony Mailer mail solution for Yii framework 2.0.

For license information check the LICENSE-file.

Requirements

PHP 8.1 or higher.

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist yiisoft/yii2-symfonymailer

or add

"yiisoft/yii2-symfonymailer": "~3.0.0"

to the require section of your composer.json.

Usage

To use this extension, simply add the following code in your application configuration:

return [
    //....
    'components' => [
        'mailer' => [
            'class' => \yii\symfonymailer\Mailer::class,            
            'transport' => [
                'scheme' => 'smtps',
                'host' => '',
                'username' => '',
                'password' => '',
                'port' => 465,
                'dsn' => 'native://default',
            ],
            'viewPath' => '@common/mail',
            // send all mails to a file by default. You have to set
            // 'useFileTransport' to false and configure transport
            // for the mailer to send real emails.
            'useFileTransport' => false,
        ],
    ],
];

return [
    //....
    'components' => [
        'mailer' => [
            'class' => \yii\symfonymailer\Mailer::class,            
            'transport' => [
                'dsn' => 'smtp://user:pass@smtp.example.com:25',
            ],
        ],
    ],
];

You can then send an email as follows:

Yii::$app->mailer->compose('contact/html')
     ->setFrom('from@domain.com')
     ->setTo($form->email)
     ->setSubject($form->subject)
     ->send();

DI Container

The Mailer component will automatically use the DI container when it is available. This allows you to easily override the transport factory configurations or their dependencies.

Migrating from yiisoft/yii2-swiftmailer

To migrate from the deprecated yiisoft/yii2-swiftmailer to this extension you need to update the application config.

Swiftmailer default transport was the SendmailTransport, while with this extension it will default to a NullTransport (sends no mail). You can use the swiftmailer default like the following:

'mailer' => [
    'class' => yii\symfonymailer\Mailer::class,
    'transport' => [
        'dsn' => 'sendmail://default',
    ],
],

With this extension, you do not have an ability of directly setting timeout, or other configurations that were possible with Swiftmailer extension. The reason is, the underlying Symfony package defines its classes as final thereby discouraging inheritance and pushing towards composition.

To achieve timeout, for example (and other transport configurations supported), you will need to define factory class and override default transport factory you are interested to replace through Yii DI container definitions.

Below is an example that shows you how to ovveride timeout.

First define your custom factory class.

namespace app\utils;

use Symfony\Component\Mailer\Transport\Dsn;
use Symfony\Component\Mailer\Transport\Smtp\SmtpTransport;
use Symfony\Component\Mailer\Transport\TransportFactoryInterface;
use Symfony\Component\Mailer\Transport\TransportInterface;
use yii\base\BaseObject;

final class CustomSmtpFactory extends BaseObject implements TransportFactoryInterface
{
    public float $timeout;

    public function create(Dsn $dsn): TransportInterface
    {
        $transport = $this->create($dsn);
        if ($transport instanceof SmtpTransport) {

            /** @var SocketStream $stream */
            $stream = $transport->getStream();
            $stream->setTimeout($this->timeout);
        }
        return $transport;
    }

    public function supports(Dsn $dsn): bool
    {
        return $dsn->getScheme() == 'smtp';
    }
}

Then in the root of web configuration, set the factory class in container definitions, thereby overriding the default class.

'container' => [
    'definitions' => [
        EsmtpTransportFactory::class => [
            'class' => \app\utils\CustomSmtpFactory::class,
            'timeout' => 143, //Configure it to your own timeout
        ],
        // ... other definitions
    ],
],

That is all you need to do. The extension should use your new class and its configuration settings.

Security implications of the DSN

While the DSN might seem like a simple way to allow user configurable mailer settings it should be noted that the sendmail transport allows for execution of local executables. If you need to have a user configurable DSN (which is easier to build and more powerful to use than creating a GUI) you should probably disable the sendmail transport. Any user who has the power to configure a DSN essentially has shell access to wherever the code is running.

Testing

Check the documentation testing to learn about testing.

yiisoft / yii2-symfonymailer

Maintainers

Details