README

Symfony Mailer 扩展程序 for Yii 1

此扩展程序提供了在 Yii1 应用程序中集成 Symfony Mailer 的功能。

有关许可证信息，请查看 LICENSE 文件。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令：

php composer.phar require --prefer-dist yii1tech/mailer

或者

"yii1tech/mailer": "*"

将以下内容添加到您的 composer.json 文件的 "require" 部分。

使用方法

此扩展程序为 Yii1 应用程序提供了 Symfony Mailer 的集成。应用程序配置示例

<?php

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

注意：请参阅 Symfony Mailer 手册 中有关传输 DSN 规范的说明。

使用示例

<?php

use Symfony\Component\Mime\Email;

$email = (new Email())
    ->addFrom('noreply@example.com')
    ->addTo('johndoe@example.com')
    ->subject('Greetings')
    ->text('Welcome to our application')
    ->html('<h1>Welcome to our application</h1>');

Yii::app()->mailer->send($email);

全局配置电子邮件

为了简化代码并避免重复，您可以设置默认的标题，这些标题应适用于每个发送的电子邮件。应用程序配置示例

<?php

return [
    'components' => [
        'mailer' => [
            'class' => yii1tech\mailer\Mailer::class,
            'defaultHeaders' => [
                'From' => 'My Application<noreply@example.com>',
                'Bcc' => 'test-via-bcc@example.com',
                'X-Custom-Header' => 'foobar',
            ],
            // ...
        ],
    ],
    // ...
];

模板渲染

您可以指定电子邮件正文的内文为渲染特定视图模板的结果。它与在您的 Web 控制器中渲染视图的方式相似。您需要使用 \yii1tech\mailer\TemplatedEmail 来指定模板。

<?php

use yii1tech\mailer\TemplatedEmail;

$email = (new TemplatedEmail())
    ->addFrom('noreply@example.com')
    ->addTo('johndoe@example.com')
    ->subject('Greetings')
    ->textTemplate('greetings-text') // Text Body will be set as render of 'views/mail/greetings-text.php'
    ->htmlTemplate('greetings-html') // HTML Body will be set as render of 'views/mail/greetings-html.php'
    ->context([
        'name' => 'John Doe', // variables, which will be available inside the templates
    ]);

Yii::app()->mailer->send($email); // actual rendering takes place just before the sending

默认情况下，视图模板将在应用程序基本路径中的 "views/mail" 目录中搜索。但您可以配置 \yii1tech\mailer\Mailer::$view 组件以使用不同的文件夹。您还可以为所有模板渲染设置全局布局。应用程序配置示例

<?php

return [
    'components' => [
        'mailer' => [
            'class' => yii1tech\mailer\Mailer::class,
            'view' => [
                'viewPath' => dirname(__DIR__) . '/views/mail',
                'layout' => 'default-layout',
            ],
            // ...
        ],
    ],
    // ...
];

在模板文件内部，以下变量始终可用

• $this - 对 \yii1tech\mailer\View 实例的引用。
• $_message - 对渲染的电子邮件消息实例的引用。

模板示例

<?php
/**
 * @var $this \yii1tech\mailer\View
 * @var $_message \yii1tech\mailer\TemplatedEmail
 * @var $name string
 */
 
$_message->subject('Email subject defined within the template');

$this->layout = 'particular-layout';
?>
<h1>Greetings</h1>
<p>Context var "name" = <?php echo CHtml::encode($name); ?></p>

<a href="<?php echo $this->createAbsoluteUrl('mail/unsubscribe', ['email' => $_message->getTo()[0]->getAddress()]); ?>">Unsubscribe</a>

编写单元测试

在为您的应用程序编写单元测试时，您可以使用 \yii1tech\mailer\transport\ArrayTransport。此传输将所有传入的电子邮件消息存储在内部字段中，而不是实际发送它们。应用程序配置示例

<?php

return [
    'components' => [
        'mailer' => [
            'class' => yii1tech\mailer\Mailer::class,
            'dsn' => 'array://',
            // ...
        ],
    ],
    // ...
];

单元测试示例

<?php

use Symfony\Component\Mime\Email;

class MailTest extends TestCase
{
    public function testMail(): void
    {
        // code under test here

        /** @var \yii1tech\mailer\transport\ArrayTransport $transport */
        $transport = Yii::app()->mailer->getTransport();
        
        // retrieve the last sent email message:
        $sentMessage = $transport->getLastSentMessage();
        
        $this->assetNotNull($sentMessage);
        $this->assertSame('johndoe@example.com', $sentMessage->getTo()[0]->getAddress());
        // ...
        
        // retrieve the all sent email messages. matching the callback condition:
        $messages = $transport->filterSentMessages(function (Email $message) {
            return $message->getSubject() === 'Greetings';
        });
        $this->assertCount(1, $messages);
        // ...
    }
}