README

使用模板机制发送 Mandrill 或 SendGrid 邮件的统一接口包装器。

概述

此包提供了 Mandrill 和 SendGrid 邮件发送引擎的包装器，并利用了使用已准备模板发送电子邮件的可能性。

更多信息，请参阅

两个邮件发送器都拥有统一的接口，因此更改您的邮件发送引擎相当简单。

包还增加了在代码中配置您的 Mandrill 模板并将其播种到您的 Mandrill 账户的可能性。将模板播种到 SendGrid 的功能正在开发中。

兼容性

该包与 Laravel 5.2 兼容。

SendGrid

当发送电子邮件给多个收件人时，新的 SendGrid API 在某些方面有一些缺点。为了避免破坏任何东西，SendGrid 邮件发送器将所有收件人视为 to 类型。

更多信息，请参阅 https://github.com/sendgrid/sendgrid-php#please-read-this。

安装

版本 >= 2.0

将 hydreflab/laravel-mailer 添加到您的 composer.json

 {
     "require": {
         "hydreflab/laravel-mailer": "2.*"
     }
 }

如果您将使用 Mandrill，请将 weblee/mandrill 添加到您的 composer.json

{
    "require": {
        "weblee/mandrill": "dev-master"
    }
}

如果您将使用 SendGrid，请将 sendgrid/sendgrid 添加到您的 composer.json

{
    "require": {
        "sendgrid/sendgrid": "4.0.*"
    }
}

将 DeSmart\Mailer\MailerServiceProvider::class 添加到您的 config/app.php 文件。
发布邮件发送器配置： php artisan vendor:publish。这将创建 config/mailer.php 文件。

邮件发送器配置基于 .env 条目

 MAILER_DRIVER=mandrill or sendgrid
 MAILER_API_KEY=YOUR_API_KEY
 DEFAULT_MAIL_FROM=mailer@example.com
 DEFAULT_MAIL_NAME=Mailer

（仅 Mandrill 使用） 如果您想使用模板创建/更新功能
1. 将 DeSmart\Mailer\Mandrill\MandrillTemplatesSeedCommandServiceProvider::class 添加到您的 config/app.php 文件。
2. 发布 Mandrill 模板配置： php artisan vendor:publish。这将创建 config/mandrill-templates.php 文件，您可以在其中配置您的 Mandrill 模板。此配置由 mandrill_templates:seed artisan 命令使用。
3. 重要步骤 5.i 和 5.ii 应在安装 Mailer 包之后执行 - 这是因为模板播种器使用要首先发布的邮件发送器配置。

版本 < 2.0

包仅实现了 Mandrill 的包装器。

如果可能，请使用版本 >= 2.0

将 hydreflab/laravel-mailer 添加到您的 composer.json

 {
     "require": {
         "hydreflab/laravel-mailer": "1.*"
     }
 }

将 DeSmart\Mailer\ServiceProvider\MandrillServiceProvider::class 添加到您的 config/app.php 文件。
发布 Mandrill 模板配置： php artisan vendor:publish。这将创建 config/mandrill-templates.php 文件，您可以在其中配置模板。此配置由 mandrill_templates:seed artisan 命令使用。
Mandrill 邮件发送器使用默认发件人电子邮件和名称的配置。您可以在 config/mail.php 文件中找到它
```
 'from' => ['address' => null, 'name' => null],
```
在您的 .env 文件中设置适当的 API 密钥
```
 MANDRILL_SECRET=YOUR_API_KEY
```

界面概述

包为两个邮件发送器提供统一的接口

interface MailerInterface
{
    /**
     * @param string $email
     * @return void
     */
    public function setFromEmail($email);

    /**
     * @param string $name
     * @return void
     */
    public function setFromName($name);

    /**
     * @param string $subject
     * @return void
     */
    public function setSubject($subject);

    /**
     * @param string $template
     * @return void
     */
    public function setTemplate($template);

    /**
     * @param string|null $subject
     * @param string|null $template
     * @return bool
     */
    public function send($subject = null, $template = null);

    /**
     * @param string $queue
     * @param string|null $subject
     * @param string|null $template
     * @return bool
     */
    public function queue($queue, $subject = null, $template = null);

    /**
     * @param Recipient $recipient
     * @return void
     */
    public function addRecipient(Recipient $recipient);

    /**
     * @param Header $header
     * @return void
     */
    public function addHeader(Header $header);

    /**
     * @param string $email
     * @return void
     */
    public function setReplyTo($email);

    /**
     * @param Variable $variable
     * @return void
     */
    public function addGlobalVariable(Variable $variable);

    /**
     * @param Recipient $recipient
     * @param Variable $variable
     * @return void
     */
    public function addLocalVariable(Recipient $recipient, Variable $variable);

    /**
     * @param Attachment $attachment
     * @return void
     */
    public function addAttachment(Attachment $attachment);

    /**
     * @return array
     */
    public function getData();

    /**
     * @param array $data
     * @return void
     */
    public function setData(array $data);
}

setFromEmail()：覆盖默认电子邮件发送者；接受 string 参数
setFromName()：覆盖默认电子邮件发送者名称；接受 string 参数
setSubject()：设置电子邮件主题；接受 string 参数
setTemplate()：设置模板标识符；接受 string 参数
addRecipient()：向消息中添加收件人；需要传入Recipient对象作为参数
addHeader()：向消息中添加正确的SMTP头；需要传入Header对象作为参数
setReplyTo()：设置回复邮箱；需要传入string类型的参数
addGlobalVariable()：添加所有收件人共享的变量（在Mandrill中相当于全局合并变量，在SendGrid中相当于部分）；需要传入Variable对象作为参数
addLocalVariable()：添加指定收件人的变量（在Mandrill中相当于合并变量，在SendGrid中相当于替换）；需要传入Recipient和Variable对象作为参数
addAttachment()：向消息中添加附件；需要传入Attachment对象作为参数
send()：将消息发送到之前定义的收件人；可以传入（如果之前未设置）邮件主题（string）和模板标识符（string）
queue()：将邮件添加到队列（使用Laravel队列机制）；必须传入队列名称（string）作为第一个参数；也可以传入（如果之前未设置）邮件主题（string）和模板标识符（string）
getData()：获取邮件发送器的完整配置，即收件人、变量、头信息等；返回array
setData()：设置邮件发送器的配置；需要传入array

收件人对象

收件人对象描述了收件人的详细信息。

收件人对象需要三个参数

收件人姓名：string
收件人邮箱：string
收件人类型（可选）：RecipientType对象（如果未传入收件人类型，类型将被设置为to）

收件人类型对象

收件人类型对象描述了收件人的类型——他要么是

主要收件人（to），要么
应该被抄送（cc），或者
应该被隐秘抄送（bcc）。

收件人类型对象是一个简单的值对象，具有命名构造函数

RecipientType::to()
RecipientType::bcc()
RecipientType::cc()

变量对象

变量对象描述了用于个性化电子邮件内容的变量的详细信息。变量（通过其名称定义）放置在电子邮件模板中。

变量对象需要两个参数

变量名称：string
变量值：string

头信息对象

头信息对象描述了SMTP头信息的详细信息。有关可接受头信息的更多详细信息，请参阅Mandrill/SendGrid API文档。

头信息对象需要两个参数

变量名称：string
变量值：string

附件对象

附件对象包含有关附加到消息的文件的数据。对象中设置的内容应为纯文本。

对于Mandrill，内容在传递到API时将被base64编码。

对于SendGrid，将创建包含内容的临时文件，然后传递该文件的路径到API。在消息发送后，临时文件将被删除。

附件对象需要三个参数

附件MIME类型：string
附件文件名：string
附件内容（纯文本）：string

用法

PHP

class Notifier
{
    protected $mailer;

    public function __construct(\DeSmart\Mailer\MailerInterface $mailer)
    {
        $this->mailer = $mailer;
    }

    public function notify()
    {
        // If you want to override default sender email and name
        $this->mailer->setFromEmail('johndoe@example.com');
        $this->mailer->setFromName('John Doe');
        
        // You can set subject and template identifier
        $this->mailer->setSubject('Test subject');
        $this->mailer->setTemplate('test-template');

        // To add recipient
        $this->mailer->addRecipient(new Recipient('Jane Doe', 'janedoe@example.com'));
        // or
        $this->mailer->addRecipient(new Recipient('Jane Doe', 'janedoe@example.com'), RecipientType::to());

        // To add BCC recipient
        $this->mailer->addRecipient(new Recipient('Jane Doe', 'janedoe@example.com', RecipientType::bcc()));

        // To add CC recipient
        $this->mailer->addRecipient(new Recipient('Jane Doe', 'janedoe@example.com'), RecipientType::cc());

        // To add global variable (shared between all recipients)
        $this->mailer->addGlobalVariable(new Variable('variable_name', 'variable_value');

        // To add local variable (for specified recipient)
        $this->mailer->addLocalVariable(
            new Recipient('John Doe', 'johndoe@example.com'),
            new Variable('variable_name', 'variable_value')
        );

        // To add attachment
        $this->mailer->addAttachment(new Attachment('application/pdf', 'attachment.pdf', 'PDF content in plain text'));
        $this->mailer->addAttachment(new Attachment('text/html', 'attachment.txt', 'Txt file content in plain text'));

        // To set reply to
        $this->mailer->setReplyTo('reply-to@example.com');
        // or (Mandrill only)
        $this->mailer->addHeader(new Header('Reply-To', 'reply-to@example.com')

        // To send email
        $this->mailer->send();
        // or to send email if subject and/or template was not set before
        $this->mailer->send('Test subject', 'test-template');
        
        // To add email to queue
        $this->mailer->queue();
        // or to add email to defined queue 
        $this->mailer->queue('queue_name');
        // or to add email to queue if subject and/or template was not set before
        $this->mailer->queue('queue_name', 'Test subject', 'test-template');
    }
}

Mandrill模板

要配置您的模板，编辑config/mandrill-templates.php文件

'User registration email' => [
    'from_email' => null,
    'from_name' => null,
    'subject' => 'Confirm Your Account!',
    'code' => file_get_contents(__DIR__ . '/mandrill-templates/user-registration-email.phtml'),
    'text' => null,
    'publish' => true,
    'labels' => array(),
],

当您的配置就绪后，您可以运行php artisan mandrill_templates:seed命令来创建和/或更新Mandrill模板。

hydreflab / laravel-mailer

维护者

详细信息