README

Fluent Web服务的PHP客户端。Fluent是一种简单优雅的方式来从您的Web或移动应用程序创建和发送事务性电子邮件。

安装

要安装Fluent for PHP，只需拉取composer包

composer require fivesqrd/fluent:4.*

对于Laravel项目，有一个易于安装的包可用

composer require fivesqrd/fluent-laravel

有关Laravel配置选项和Fluent外观的更多信息，请参阅此处： https://github.com/fivesqrd/fluent-laravel

优点

• 在开发、测试和生产环境中提供一致性
• 安全的邮件测试沙盒，不会骚扰您的用户
• 带有60天内容保留期的邮件日志
• 使用Jit减少与表格和内联CSS的斗争

注册

要发送消息，您首先需要注册Fluent账户。注册后，您将收到API密钥，以便立即开始发送消息。

对象实例化

在运行时向消息对象传递配置

$config = [
    'key'           => null, // Fluent access key
    'secret'        => null, // Fluent access secret
    'headers'       => null, // Optional default sender
];

$delivery = (new Fluent\Delivery($config))->create();
$events = (new Fluent\Event($config))->find();

为了使引导过程更容易，我们提供了一种通过将选项分配给Factory类的静态$defaults属性来预载配置的方法

Fluent\Factory::$defaults = [
    'key'           => null, // Fluent access key
    'secret'        => null, // Fluent access secret
    'headers'       => null, // Optional default sender
];

$message = Fluent\Factory::message()->create();
$events = Fluent\Factory::event()->create();

消息投递

可以通过将消息体与Fluent Web服务客户端结合来轻松投递消息。

$body = (new Fluent\Body())
    ->title('My little pony')
    ->paragraph('Lorem ipsum dolor sit amet, consectetur adipiscing elit.')
    ->number(['caption' => 'Today', 'value' => date('j M Y')])
    ->button('http://www.mypony.com', 'Like my pony')
    ->paragraph('Pellentesque habitant morbi tristique senectus et netus et malesuada fames.');

$messageId = (new Fluent\Delivery())->create()
    ->content($body)
    ->subject('Testing it')
    ->from('me@myapp.com', 'My App')
    ->to('user@theirdomain.com')
    ->send();

以下方法可用于设置消息的投递

subject($text)

/* Add a subject to the message */
$message->subject('Lorem ipsum dolor');

header($key, $value) 或 headers($values)

/* Add a header to the message */
$message->header('Reply-To', 'me@myapp.com');

/* Add multiple headers to the message */
$message->headers(array(
    'Reply-To', 'me@myapp.com',
    'X-Fluent', 'lorem'
));

from($address, $name = null)

/* Set the sender address and name */
$message->from('me@myapp.com', 'My App');

to($address, $name = null)

注意：每条消息只能提供一个收件人。

/* Set the recipient address and name */
$message->to('user@theirdomain.com');

attach($filename, $mimetype, $blob) 或 attachments($values)

/* Add an attachment to the message */
$message->attach('My-Attachment.pdf', 'application/pdf', file_get_contents($file))

/* Add multiple attachments to the message */
$message->attachments(array(
    ['name' => 'My-First-File.pdf', 'type' => 'application/pdf', 'content' => file_get_contents($file)],
    ['name' => 'My-2nd-File.jpg', 'type' => 'image/jpg', 'content' => file_get_contents($file2)],
));

send()

send是链中的最终方法，应始终最后调用。它将消息投递到Fluent Web服务，并返回一个唯一的消息ID。

/* Send the message */
$messageId = $message->send();

模板

使用预构建的模板类可以简化正文构建和消息投递

/* Double action: construct and send */
$template = new MyApp\Template\PasswordReset($params);

$messageId = (new Fluent\Delivery())->from($template)->send();

附加功能

带有自定义标头发送

$messageId = (new Fluent\Delivery())->create()
    ->content($body)
    ->header('Reply-To', 'me@myapp.com')
    ->to('user@theirdomain.com')
    ->send(); 

带有附件发送

$messageId = (new Fluent\Delivery())->create()
    ->content($body)
    ->subject('Testing it')
    ->attach('My-Attachment.pdf', 'application/pdf', file_get_contents($file))
    ->to('user@theirdomain.com')
    ->send();

更多Web服务功能

重发消息

在大多数情况下，由于应用状态已更改，重新发送电子邮件通知很难，因为必须重新创建，但Fluent可以简单地重发原始消息的快照。可选地指定不同的收件人。

$response = (new Fluent\Delivery())->resend($messageId)
    ->to('other@theirdomain.com')
    ->send();

检索已发送的消息

$response = (new Fluent\Message())->get($messageId)->fetch();

搜索已发送的消息

$response = (new Fluent\Message())->find()
    ->from('me@myapp.com')
    ->to('user@theirdomain.com')
    ->since(date('Y-m-d H:i:s', strtotime('-2 days ago')))
    ->fetch();

查找事件

获取特定收件人地址的投递进度更新

$response = (new Fluent\Event())->find()
    ->to('user@theirdomain.com')
    ->since(date('Y-m-d H:i:s', strtotime('-2 days ago')))
    ->type(['hard_bounce', 'soft_bounce', 'reject'])
    ->fetch();

替代格式

有时您需要发送纯文本或自定义HTML电子邮件。Fluent提供了这样做的方法

纯文本

$messageId = (new Fluent\Message())->create('This is my plain text message body')
    ->subject('Testing it')
    ->header('Reply-To', 'me@myapp.com')
    ->to('user@theirdomain.com')
    ->send();

自定义HTML

$html = '<html><body><p>This is my custom HTML message body</p></html></body>';

$messageId = (new Fluent\Message())->create(new Fluent\Message\Content\Raw($html))
    ->subject('Testing it')
    ->header('Reply-To', 'me@myapp.com')
    ->to('user@theirdomain.com')
    ->send();

在本地生成HTML

除了投递消息外，还可以在本地渲染HTML文档。为此，我们使用了我们的开源电子邮件设计之一Musimal，并将其封装在PHP库中。它接受Body对象作为参数，并返回一个响应式的HTML电子邮件正文字符串。

# add the open source HTML wrapper to the project
composer require fivesqrd/fluent-musimal

从Body对象生成响应式HTML字符串

/* Predefine the HTML rendering options */
$options = array(
    'logo'          => 'My App', //Plain text or publicly available URL. Image not wider than 200px
    'color'         => '#ff6600', //Primary colour
    'footer'        => 'My test generated by Musimal for PHP', //Text at bottom of all messages
);

/* Construct a message body */
$body = (new Fluent\Body())
    ->title('My little pony')
    ->paragraph('Lorem ipsum dolor sit amet, consectetur adipiscing elit.')
    ->number(['caption' => 'Today', 'value' => date('j M Y')])
    ->button('http://www.mypony.com', 'Like my pony')
    ->paragraph('Pellentesque habitant morbi tristique senectus et netus et malesuada fames.');

/* Render the body to an HTML document */
$html = (new Fluent\Layout($options))->render($body);