README

Mailer 组件使您能够使用不同的支持协议发送电子邮件。

安装组件

安装组件的最佳方式是使用 Composer。

composer require webiny/mailer

要查看包的其他版本，请访问Packagist 页面。

用法

当前支持的协议有

• SMTP（您也可以通过他们的 SMTP API 使用 Mandrill 和 Sendgrid）
• PHP 的 mail() 函数
• Sendmail
• Mandrill（《Mandrill API 文档》）
• Sendgrid（《Sendgrid API 文档》）

要使用此组件，您首先需要在组件配置文件中设置配置。如果您打开 ExampleConfig.yaml，您将看到两个示例配置集，Demo 和 Gmail。按照此示例创建自己的配置集。

以下是一个示例配置

    Mailer:
        Default:
            CharacterSet: utf-8
            MaxLineLength: 78
            Priority: 2
            Sender:
                Email: nikola@tesla.com
                Name: Nikola Tesla
            Transport:
                Type: smtp
                Host: smtp.gmail.com
                Port: 465
                Username: me@gmail.com
                Password: ***
                Encryption: ssl
                AuthMode: login
            AntiFlood:
                Threshold: 99
                Sleep: 1
            DisableDelivery: false
        Mandrill:
            Mode: template # template or html
            ApiKey: yourApiKey
            DisableDelivery: false
            Message:    # these are all optional
                FromEmail: ''
                FromName: ''
                Headers: []
                Important: false
                TrackOpens: null
                TrackClicks: null
                AutoText: null
                AutoHtml: null
                InlineCss: null
                UrlStripQs: null
                PreserveRecipients: null
                ViewContentLink: null
                BccAddress: ''
                TrackingDomain: null
                SigningDomain: null
                ReturnPathDomain: null
                Merge: true
                MergeLanguage: mailchimp
                Tags: []
                Subaccount: null
                GoogleAnalyticsDomains: []
                GoogleAnalyticsCampaign: ''
                Metadata: []
                RecipientMetadata: []
                Attachments: []
        Sendgrid:
            ApiUser: yourApiUser
            ApiKey: yourApiKey
            DisableDelivery: false
            Decorators:
                Wrapper: ['*|', '|*']

您可以有无限多的配置集。

要将配置注册到组件中，只需调用 Mailer::setConfig($pathToYamlConfig)。

根据定义的 Transport.Type，可能需要其他传输参数。

配置参数

Mailer 配置由几个参数组成，这些参数在接下来的几节中进行了说明。

注意：一些配置参数是特定于桥接器的，例如 AntiFlood 参数。默认桥接器是 SwiftMailer，它当然支持 AntiFlood 措施。

字符集（CharacterSet）

这是在编码电子邮件内容时将使用的默认字符集。默认情况下，字符集设置为 utf-8，它支持大多数语言字符。您可能需要更改某些语言的字符集，例如日语。

发件人（Sender）

这是在您的出站电子邮件上设置的默认发件人。

传输（Transport）

传输配置块包含以下参数

• 类型
  • 定义连接类型
  • 可以是 smtp、mail 或 sendmail

这些参数仅在 SMTP 连接的情况下需要

• 主机
  • 定义 smtp 主机的位置
• 端口
• • 连接到主机使用的端口
  • 端口号根据定义的 encryption 和 auth_mode 而变化
• 用户名
  • 连接到主机所需的用户名
• 密码
  • 连接到主机所需的密码
• 加密
  • 用于连接的加密方式
  • 此参数是可选的
  • 可以是 ssl 或 tls，具体取决于您的宿主
• 认证模式
  • 用于连接到主机的认证模式
  • 此参数是可选的
  • 可以是 plain、login、cram-md5 或 null

反垃圾邮件（AntiFood）

一些邮件服务器有一套安全措施，限制您在每个连接或某些时间间隔内可以发送的电子邮件数量。这主要是为了阻止垃圾邮件使用他们的服务，但有时这也可能给非垃圾邮件发送者造成问题。为了避免触碰到这些安全措施，AntiFood 参数可以限制您在每个连接中可以发送的电子邮件数量以及您需要等待多长时间才能建立新的连接。

不用担心断开连接、再次连接并继续发送电子邮件...这一切都是完全自动化的，您不需要做任何事情。

AntiFood 参数由两个属性组成

• 阈值
  • 定义每次连接中要发送的电子邮件数量
• 睡眠
  • 定义了等待多少秒后才能建立新的连接并恢复发送

用法

使用Mailer组件非常简单，只需实现MailerTrait，构建消息并发送。

以下是一个简单的使用示例

class MyClass
{
    use \Webiny\Component\Mailer\Bridge\MailerTrait;

	function sendEmail() {
		// get the Mailer instance
		$mailer = $this->mailer('Default');

		// let's build our message
		$msg = $mailer->getMessage();
		$msg->setSubject('Hello email')
			->setBody('This is my test email body')
			->setTo(new Email('me@gmail.com', 'Jack'));

		// send it
		$mailer->send($msg);
	}
}

现在假设你有多位发送者，并且你想发送相同的电子邮件给所有人，但只是稍微有所不同，例如，在每个电子邮件中都加上特定用户的姓名。

class MyClass
{
	use \Webiny\Component\Mailer\Bridge\MailerTrait;

	function sendEmail() {
		// get the Mailer instance
		$mailer = $this->mailer('Default');


		// let's build our message
		$msg = $mailer->getMessage();
		$msg->setSubject('Hello email')
			 ->setBody('Hi {name},
						   This is your new password: <strong>{password}</strong>.')
			 ->setTo([
					new Email('jack@gmail.com'),
					new Email('sara@gmail.com')
					]);

		// before sending, let's define the decorator replacements
		$replacements = [
			'jack@gmail.com' => [
				'name'     => 'Jack',
				'password' => 'seCre!'
			],

			'sara@gmail.com' => [
				'name'     => 'Sara',
				'password' => 'Log!n'
			]
		];
		$mailer->setDecorators($replacements);

		// send it
		$mailer->send($msg);
	}
}

桥接器

默认桥接库是SwiftMailer（http://swiftmailer.org/）。

如果你希望创建自己的驱动程序，你需要创建三个类

• 消息
  • 这个类应该实现\Webiny\Component\Mailer\Bridge\MessageInterface
  • 这个类用于填充消息属性，如发送者、正文...
• 传输
  • 这个类应该实现\Webiny\Component\Mailer\Bridge\TransportInterface
  • 它用于发送消息
• Mailer
  • 这个类应该实现\Webiny\Component\Mailer\Bridge\MailerInterface
  • 这个类只有两个方法，一个返回Message实例，另一个返回Transport实例

资源

要运行单元测试，需要使用以下命令

$ cd path/to/Webiny/Component/Mailer/
$ composer.phar install
$ phpunit