README

用于通过SparkPost的REST API发送邮件的CakePHP插件

简介

什么是SparkPost？

SparkPost 是一种基于网络的邮件投递服务，允许网络应用开发者通过灵活可靠的REST API发送交易性邮件。你可能听说过其他邮件投递服务，如 Mandrill 和 SendGrid。

遗憾的是，这些服务要么不是免费的，要么曾经是免费的，但现在已经不再免费了。幸运的是，如果你每月发送的邮件少于15,000封（大多数初创网络应用都是这样），通过SparkPost发送邮件是免费的。

Syntax Era 开发了这个插件，因为我们的大部分应用程序都使用了 CakePHP，而且我们注意到没有 CakePHP 插件用于 SparkPost。我们希望这个插件能够对整个 CakePHP 社区有用，特别是那些从 Mandrill 或其他付费邮件服务迁移过来，但仍未准备好/有能力支付他们发送的少量交易性邮件的人。

交易性邮件...？

交易性邮件是用于通知用户某事或有时提示用户完成某个操作的邮件。例如，密码重置邮件、账户验证邮件和“你刚刚收到一条消息”邮件都是交易性的。

有关更多信息，请参阅什么是交易性邮件？。

什么是CakePHP？

CakePHP 是一种快速开发的 PHP 网络应用程序框架，它使用 MVC（模型/视图/控制器）架构。它于2005年8月首次发布，现在是3.0版本，比以往任何时候都更加强大！CakePHP 的一个优点是它支持通过插件扩展其自身功能，而这个插件就是其中之一。

有关 CakePHP 的更多信息，请访问他们的网站 CakePHP.org。

安装

命令行安装

使用 Composer 是安装此插件的首选方式，因为它允许你轻松下载插件及其依赖项，并保持它们更新，并利用 Composer 的出色类自动加载器。

要使用 Composer 安装插件

打开终端并 cd 到你的 CakePHP 应用程序的根目录。
运行 composer require syntaxera/cakephp-sparkpost-plugin 下载插件及其依赖项。
如果你愿意，打开 composer.json 进行编辑，并将插件的版本控制方案修改为你想要的。

手动安装

你也可以通过点击上面的“下载ZIP”按钮手动安装插件，并将其解压缩到你的 CakePHP 应用程序的 plugins/ 目录中，但是如果你这样做，你也必须手动执行更新。

如果你熟悉 git，你也可以使用 git clone 直接将仓库下载到你的硬盘上。这允许你保持插件开发的最新状态，但警告你，“尖端”是有原因的。

设置

要将插件添加到你的应用程序中，请在应用程序的引导文件中激活插件

Plugin::load('SparkPost');

然后，将以下内容添加到你的应用程序的配置文件中

'SparkPost' => [
    'Api' => [
        'key' => 'YOUR_SPARKPOST_API_KEY'
    ]
]

用法

因为插件作为传输实现，所以你可以从 CakePHP 应用的任何一层使用它。

从控制器中

// Configure email transport
Email::configTransport('sparkpost', [
    'className' => 'SparkPost.SparkPost',
    'apiKey' => Configure::read('SparkPost.Api.key')
]);

// Create email message
$email = new Email();
$email->transport('sparkpost');

$email->from(['FROM_ADDRESS' => 'FROM_NAME']);
$email->to(['TO_ADDRESS' => 'TO_NAME']);
$email->subject('SUBJECT');
$email->send('BODY');

从 Cake CLI 中

与从控制器发送的过程完全相同，但是您还应该使用 $email->domain('www.example.com'); 指定您的主机名，因为 CLI 环境没有主机名。

测试

您可以使用 CakePHP 内置的 PHPUnit 支持来测试插件，但这假设了以下两点：

您已全局安装 PHPUnit 并且可以通过命令行访问 phpunit 命令。
您没有删除与新的 CakePHP 3.x 应用程序一起创建的 phpunit.xml.dist 文件。

要测试插件，首先将其测试套件添加到应用的 PHPUnit 配置文件中。

<?xml version="1.0" encoding="UTF-8"?>

<phpunit ...>
    ...
    <testsuites>
        <testsuite name="App Test Suite">
            <directory>./tests/TestCase</directory>
        </testsuite>

        <!-- Add these lines -->
        <testsuite name="SparkPost Plugin Test Suite">
            <directory>./vendor/syntaxera/cakephp-sparkpost-plugin/tests/TestCase</directory>
        </testsuite>
    </testsuites>
    ...
</phpunit>

接下来，切换到应用的根目录，然后运行 phpunit。

如果不起作用，请运行 composer dump-autoload 并再次尝试。

贡献

错误报告

如果您在插件中发现错误，或者知道您想要添加的功能缺失，请随意在问题页面上创建一个问题。 在报告错误时，请尽可能详细。包括错误发生时您正在做什么，可能是什么原因导致它发生，以及如果可能的话，如何重现它。截图也很有用。

为了表示礼貌，请在创建新问题之前使用搜索工具确认问题尚未被报告。您可以在开放的错误/特性请求中添加评论/+1，但重复的问题需要花费时间修剪，并可能排挤新的、重要的问题。

拉取请求

发现了一个你认为可以修复的错误？当然，请继续前进！克隆受影响的分支，修复错误，然后创建拉取请求。我们会尽快审查并接受它。然而，在提交拉取请求之前，请确保您的代码遵循我们的代码风格指南。不遵循风格指南的 PR 将被拒绝！（当然，礼貌地）

关于分支的一些话...

在 Syntax Era，我们认为某些软件应该是免费的，而这个插件绝对属于这一类。这就是为什么我们使这个存储库公开，并允许社区贡献。如果您想将这个项目引向不同的方向，那么请fork这个仓库并继续开发！ 然而，由于我们没有对 fork 中的源代码的控制权，因此我们无法为该软件提供支持。 使用它时请自行承担风险。

法律

许可

在 MIT 许可证（MIT）下许可。有关详细信息，请参阅 LICENSE.md。

dallasmakerspace / cakephp-sparkpost-plugin

维护者

详情