README

这是您应使用以向 Mail Api 发送电子邮件的客户端。

客户端可以使用两种类型的传输来发送电子邮件

• 由 BeanstalkProxyTransport 实现的异步传输
• 由 BasicTransport 实现的同步传输

BeanstalkProxyTransport 通过将电子邮件属性发送到 Beanstalkd 队列，将 API 消费委托给工作者。

BasicTransport 使用 经典 HTTP 层来发送电子邮件。

如果设置了异步传输，它将作为默认传输。如果异步传输失败，则同步传输将是回退。

安装

将此需求添加到您的 composer.json： "fei/mailer-client": : "^1.0.0"

或在您的终端中执行 composer.phar require fei/mailer-client。

快速入门

让我们从一个简单的客户端开始

<?php

require __DIR__ . '/vendor/autoload.php';

use Fei\Service\Mailer\Client\Mailer;
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Mailer\Entity\Mail;

// The client
$mailer = new Mailer([
    Mailer::OPTION_BASEURL => 'https://api_host',
    Mailer::OPTION_HEADER_AUTHORIZATION => 'key'
]);
// Optional: a BasicTransport will be instantiate if no synchronous transport was found
$mailer->setTransport(new BasicTransport());

// The mail to send
$message = new Mail();
$message->setSubject('Test subject');
$message->setTextBody('This is a example message');
$message->addRecipient('to@test.com');
$message->setSender(array('sender@test.com'));

// And send !
$return = $mailer->transmit($message);

if ($return) {
    echo 'Mail transmit success' . PHP_EOL;
} else {
    echo 'Mail transmit failed' . PHP_EOL;
}

请记住，您应该始终通过依赖注入组件初始化邮件客户端，因为它至少需要一个依赖项，即传输。此外，OPTION_BASEURL 参数也应依赖于环境。

实际示例

以下是一个更健壮的示例，它使用 BeanstalkProxyTransport 作为默认传输。

<?php

require __DIR__ . '/vendor/autoload.php';

use Fei\ApiClient\Transport\BasicTransport;
use Fei\ApiClient\Transport\BeanstalkProxyTransport;
use Fei\Service\Mailer\Client\Mailer;
use Fei\Service\Mailer\Entity\Mail;
use Pheanstalk\Pheanstalk;

$mailer = new Mailer([
    Mailer::OPTION_BASEURL => 'https://api_host',
    Mailer::OPTION_HEADER_AUTHORIZATION => 'key'
]);

$async = new BeanstalkProxyTransport();
$async->setPheanstalk(new Pheanstalk('host'));
// Async transport will be the default transport. 
$mailer->setAsyncTransport($async);
// If async transport fails, then BasicTransport will take over.
$mailer->setTransport(new BasicTransport());

$message = new Mail();
$message->setSubject('Test subject');
$message->setTextBody('This is a example message');
$message->addRecipient('to@test.com');
$message->setSender(array('sender@test.com'));

$return = $mailer->transmit($message);

if ($return) {
    echo 'Mail transmit success' . PHP_EOL;
} else {
    echo 'Mail transmit failed' . PHP_EOL;
}

为了正常工作，BeanstalkProxyTransport 需要一个能够监听其请求的 Beanstalkd 服务器实例。工作者将消耗 Beanstalkd 消息管（或队列），并将电子邮件数据发送到 Mail API 服务器。

消息工作流程

Client -> Pheanstalkd -> Workers -> Mail API server

使用日志记录器

邮件客户端是 Logger 客户端感知。您可以像以下示例那样设置日志记录器实例，以激活日志记录功能。

<?php

$logger = new Logger([
    Logger::OPTION_BASEURL => 'http://127.0.0.1:8082',
    Logger::OPTION_FILTER => Notification::LVL_INFO,
    Logger::OPTION_HEADER_AUTHORIZATION => 'key'
]);
$logger->setTransport(new BasicTransport());

$mailer = new Mailer([
    Mailer::OPTION_BASEURL => 'https://api_host',
    Mailer::OPTION_HEADER_AUTHORIZATION => 'key'
]);
$mailer->setTransport(new BasicTransport());
$mailer->setLogger($logger); // Set and activate the the logger functionality

因此，每封发送的邮件都将通过日志记录器服务进行记录。

电子邮件和附件

以下是一个需要发送带有附件的电子邮件的示例

<?php

require __DIR__ . '/vendor/autoload.php';

use Fei\Service\Mailer\Client\Mailer;
use Fei\ApiClient\Transport\BasicTransport;
use Fei\Service\Mailer\Entity\Mail;
use Fei\Service\Mailer\Entity\Attachment;

$message = new Mail();
$message->setSubject('Test subject');
$message->setTextBody('This is a example message');
$message->setHtmlBody('<p>This is a <strong>example</strong> message!</p>');
$message->setRecipients(array('to@test.com' => 'Name', 'other@test.com' => 'Other Name'));
$message->addCc('cc@example.com', 'CC');
$message->addBcc('bcc@example.com', 'CC');
$message->setSender(array('sender@test.com' => 'The sender'));
$message->setReplyTo(array('steve@app.com' => 'Steve'));

// Add a attachment with a \SplObjectFile
$message->addAttachment(new \SplFileObject('/to/file/path/image.png'));

// Or add a attachment with a "generated string"
$attachment = array(
    'filename' => 'document.txt',
    'mime_type' => 'text/plain',
    // Note base64_encode
    'contents' => base64_encode('Hello world!') . PHP_EOL
);
$message->addAttachment($attachment);

// Or add a attachment object
$attachment = new Attachment('/to/file/path/document.pdf');
$attachment->setAttachmentFilename('another-filename.txt');
$attachment->setMimeType('text/plain');
$message->addAttachment($attachment);

$mailer = new Mailer([
    Mailer::OPTION_BASEURL => 'https://api_host',
    Mailer::OPTION_HEADER_AUTHORIZATION => 'key'
]);
$mailer->setTransport(new BasicTransport());
$mailer->transmit($message);

嵌入附件

有时，您需要在消息中内嵌图像（或其他媒体）。您可以使用资源 URL 来链接媒体，但这种方法通常会被邮件客户端阻止。另一种方法是直接在消息中嵌入您的媒体。

<?php

use Fei\Service\Mailer\Entity\Mail;
use Fei\Service\Mailer\Entity\Attachment;

$message = new Mail();

$embedded = (new Attachment('/my/picture.png', true));
$message->addAttachment($embedded);

$message->setTextBody('This is a example message');
$message->setHtmlBody(<<<HTML
<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Example</title>
</head>
<body>
    <p>
        <img src="{$embedded->getCid()}" style="display: block; width: 100px; height: 100px; float: right;">
        This is example with a embedded image
    </p>
</body>
</html>
HTML
);

就是这样。

全部捕获

在非生产环境中，您通常不需要向实际收件人发送电子邮件。出于测试目的，您可以使用选项 OPTION_CATCHALL_ADDRESS 初始化客户端，所有电子邮件都将转发到传递给此选项的电子邮件地址。

<?php

use Fei\Service\Mailer\Client\Mailer;

$mailer = new Mailer([
    Mailer::OPTION_BASEURL => 'https://api_host',
    Mailer::OPTION_CATCHALL_ADDRESS => 'testing@email.com',
    Mailer::OPTION_HEADER_AUTHORIZATION => 'key'
]);

在 Mail 实例验证之前添加回调函数

对于不同的需求，您可以在 Mail 验证之前注册一个回调来应用。

您可以将此视为扩展 "mailer-client" 功能的另一种方式。

<?php

use Fei\Service\Mailer\Client\Mailer;
use Fei\Service\Mailer\Entity\Mail;

$mailer = new Mailer();
$mailer->addCallbackBeforeValidation(function (Mail $mail) {
    $mail->setRecipients(['another@email.com']);
});

使用此示例，所有通过此客户端发送的 Mail 将将其收件人更改为 another@email.com。

我们提供了一些其他方法来管理回调

• Mailer::addFirstCallbackBeforeValidation：在堆栈的起始位置附加回调以执行，与 addCallbackBeforeValidation 相比，它将回调放置在执行链的末尾。
• Mailer::clearCallbackBeforeValidation：删除堆栈中注册的所有回调

价格集成：认识 PricerMailer 类

我们为 Pricer 需要提供了 Mailer 的子类：PricerMailer。

PricerMailer 扩展了 Mailer 的功能，并增加了一个回调，用于对将要发送的 Mail 实例进行邮件过滤。当然，您可以移除此过滤器或添加您自己的过滤器。

客户端选项

只有一个选项可用，可以传递给 __construct() 或 setOptions() 方法。