tony13tv/silverstripe-sendgrid

Sendgrid集成到Silverstripe，基于sendgrid/sendgrid分支

维护者

详细信息

github.com/tony13tv/silverstripe-sendgrid-integration

主页

源代码

安装: 281

依赖者: 0

建议者: 0

安全性: 0

星标: 1

关注者: 2

分支: 2

类型:silverstripe-module

dev-master 2016-10-03 16:09 UTC

Requires

Requires (Dev)

MIT a96431add45c40a51bb20599313f054c33f5412b

emailsendgridsendgridsilverstripeSS3

This package is auto-updated.

Last update: 2024-08-27 04:21:55 UTC

README

此库允许您使用PHP快速轻松地通过SendGrid发送电子邮件。

重要：此库需要PHP 5.3或更高版本。

BuildStatus Latest Stable Version

$sendgrid = new SendGrid('username', 'password');
$email    = new SendGrid\Email();
$email->addTo('foo@bar.com')->
       addTo('dude@bar.com')->
       setFrom('me@bar.com')->
       setSubject('Subject goes here')->
       setText('Hello World!')->
       setHtml('<strong>Hello World!</strong>');

$sendgrid->web->send($email);

安装

将SendGrid添加到您的composer.json文件中。如果您没有使用Composer，您应该使用它。这是管理PHP应用程序依赖项的绝佳方式。

{  
  "minimum-stability" : "dev",
  "require": {
    "sendgrid/sendgrid": "1.1.7"
  }
}

然后在您的PHP脚本顶部引入自动加载器

require 'vendor/autoload.php';

替代方案：从GitHub安装源代码

如果您不想使用Composer，您可以从源代码安装。

git clone https://github.com/Mashape/unirest-php.git 
git clone https://github.com/sendgrid/sendgrid-php.git

并在您的PHP脚本中包含它

require_once '/path/to/unirest-php/lib/Unirest.php';
require_once '/path/to/sendgrid-php/lib/SendGrid.php';
SendGrid::register_autoloader();

可选

如果您使用的是smtp选项，则需要swiftmailer。如果您使用的是Web API方法，则不需要此功能。

git clone git://github.com/swiftmailer/swiftmailer.git
ln -s swiftmailer/lib/swift_required.php swift_required.php

SendGrid API

SendGrid提供了两种发送电子邮件的方法：Web API和SMTP API。SendGrid建议使用SMTP API发送电子邮件。有关每种方法的优点说明，请参阅http://docs.sendgrid.com/documentation/get-started/integrate/examples/smtp-vs-rest/。

此库实现了一个通用接口，使其非常容易使用任一API。

示例应用

有一个sendgrid-php-example应用，可以帮助您快速开始开发。

用法

要开始使用此库，请使用您的SendGrid凭证初始化SendGrid对象。

$sendgrid = new SendGrid('username', 'password');

创建一个新的SendGrid Email对象并添加您的消息详细信息。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       setFrom('me@bar.com')->
       setSubject('Subject goes here')->
       setText('Hello World!')->
       setHtml('<strong>Hello World!</strong>');

使用您选择的API（Web或SMTP）发送它

$sendgrid->web->send($mail);

或

$sendgrid->smtp->send($mail);

addTo

您可以使用addTo添加一个或多个TO地址。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       addTo('another@another.com');
$sendgrid->web->send($mail);

setTos

如果您愿意，您可以使用setTos方法添加多个TO地址作为数组。这将取消之前添加的所有addTo。

$mail   = new SendGrid\Email();
$emails = array("foo@bar.com", "another@another.com", "other@other.com");
$mail->setTos($emails);
$sendgrid->web->send($mail);

getTos

有时您可能需要列出当前设置的Tos。您可以使用getTos来完成此操作。

$mail   = new SendGrid\Email();
$mail->addTo('foo@bar.com');
$mail->getTos();

removeTo

您也可能希望从您的TO集合中删除单个TO。您可以使用removeTo来完成此操作。您可以将字符串或正则表达式传递给removeTo方法。

$mail   = new SendGrid\Email();
$mail->addTo('foo@bar.com');
$mail->removeTo('foo@bar.com');

setFrom

$mail   = new SendGrid\Email();
$mail->setFrom('foo@bar.com');
$sendgrid->web->send($mail);

setFromName

$mail   = new SendGrid\Email();
$mail->setFrom('foo@bar.com');
$mail->setFromName('Foo Bar');
$mail->setFrom('other@example.com');
$mail->setFromName('Other Guy');
$sendgrid->web->send($mail);

setReplyTo

$mail   = new SendGrid\Email();
$mail->setReplyTo('foo@bar.com');
$sendgrid->web->send($mail);

addCc

$mail   = new SendGrid\Email();
$mail->addCc('foo@bar.com');
$sendgrid->web->send($mail);

Bcc

使用多个addTo作为优于setBcc的替代方案。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       addTo('someotheraddress@bar.com')->
       addTo('another@another.com')->
       ...

但如果您仍然需要Bcc，您可以执行以下操作。

$mail   = new SendGrid\Email();
$mail->addBcc('foo@bar.com');
$sendgrid->web->send($mail);

setSubject

$mail   = new SendGrid\Email();
$mail->setSubject('This is a subject');
$sendgrid->web->send($mail);

setText

$mail   = new SendGrid\Email();
$mail->setText('This is some text');
$sendgrid->web->send($mail);

setHtml

$mail   = new SendGrid\Email();
$mail->setHtml('<h1>This is an html email</h1>');
$sendgrid->web->send($mail);

端口和主机名

对于SMTP API，您可以可选地设置端口和主机名。

$sendgrid->smtp->setPort('1234567');
$sendgrid->smtp->setHostname('smtp.dude.com');

如果您使用的是本地中继，这将非常有用，如此处所述。

类别

类别用于对SendGrid提供的电子邮件统计信息进行分组。

要使用类别，只需设置类别名称。注意：每封电子邮件最多可以有10个类别。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       ...
       addCategory("Category 1")->
       addCategory("Category 2");

附件

附件目前仅基于文件，未来计划还包括内存实现。

文件附件的大小限制为每文件7 MB。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       ...
       addAttachment("../path/to/file.txt");

重要注意事项：setBcc不支持附件。这是有意为之。相反，请使用多个addTo。每个用户都将收到一个带有该设置的个性化电子邮件，并只能看到自己的电子邮件。

标准的setBcc会隐藏邮件的收件人。如果您使用多个addTo，每个用户将收到一封个性化的邮件，只显示他们的电子邮件。这更友好，也更个性化。此外，使用多个addTo是个好主意，因为setBcc不支持附件。这是设计上的。

所以，记住，当考虑“Bcc”时，请使用多个addTo。

发件人名称和回复到

有两个方便的辅助方法可以设置消息的发件人名称和回复到。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       setReplyTo('someone.else@example.com')->
       setFromName('John Doe')->
       ...

替换

替换可以用于定制多收件人电子邮件，并为用户量身定制。

$mail = new SendGrid\Email();
$mail->addTo('john@somewhere.com')->
       addTo("harry@somewhere.com")->
       addTo("Bob@somewhere.com")->
       ...
       setHtml("Hey %name%, we've seen that you've been gone for a while")->
       addSubstitution("%name%", array("John", "Harry", "Bob"));

部分

部分可以用于进一步定制面向最终用户的消息。部分只有在与替换值结合使用时才有用。

$mail = new SendGrid\Email();
$mail->addTo('john@somewhere.com')->
       addTo("harry@somewhere.com")->
       addTo("Bob@somewhere.com")->
       ...
       setHtml("Hey %name%, you work at %place%")->
       addSubstitution("%name%", array("John", "Harry", "Bob"))->
       addSubstitution("%place%", array("%office%", "%office%", "%home%"))->
       addSection("%office%", "an office")->
       addSection("%home%", "your house");

唯一参数

唯一参数用于跟踪目的。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       ...
       addUniqueArgument("Customer", "Someone")->
       addUniqueArgument("location", "Somewhere");

过滤器设置

过滤器设置用于启用和禁用应用程序，并将参数传递给这些应用程序。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       ...
       addFilterSetting("gravatar", "enable", 1)->
       addFilterSetting("footer", "enable", 1)->
       addFilterSetting("footer", "text/plain", "Here is a plain text footer")->
       addFilterSetting("footer", "text/html", "<p style='color:red;'>Here is an HTML footer</p>");

SMTP API头

SMTP API头可以用于添加现有的sendgrid功能（例如类别或过滤器），或者根据需要添加自定义头。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       ...
       addSmtpapiHeader("category", "My New Category");

消息头

您可以根据需要添加标准电子邮件消息头。

$mail = new SendGrid\Email();
$mail->addTo('foo@bar.com')->
       ...
       addMessageHeader('X-Sent-Using', 'SendGrid-API')->
       addMessageHeader('X-Transport', 'web');

一次性发送成千上万的电子邮件

有时您可能希望在一次请求中发送成千上万的电子邮件。您可以这样做。建议您将每个批次分成1000个增量。所以如果您需要发送给5000个电子邮件，那么您将将其分成每次1000个电子邮件的循环。

$sendgrid   = new SendGrid(SENDGRID_USERNAME, SENDGRID_PASSWORD);
$mail       = new SendGrid\Email();

$recipients = array("alpha@mailinator.com", "beta@mailinator.com", "zeta@mailinator.com");
$names      = array("Alpha", "Beta", "Zeta");

$email->setFrom("from@mailinator.com")->
        setSubject('[sendgrid-php-batch-email]')->
        setTos($recipients)->
        addSubstitution("%name%", $names)->
        setText("Hey %name, we have an email for you")->
        setHtml("<h1>Hey %name%, we have an email for you</h1>");

$result = $sendgrid->smtp->send($email);

忽略SSL证书验证

在使用Web API时，您可以选择忽略SSL证书的验证。

var options = array("turn_off_ssl_verification" => true);
$sendgrid   = new SendGrid(SENDGRID_USERNAME, SENDGRID_PASSWORD, options);

$email      = new SendGrid\Email();
...
$result     = $sendgrid->web->send($email);

贡献

  1. 分叉它
  2. 创建您的功能分支（git checkout -b my-new-feature）
  3. 提交您的更改（git commit -am '添加了一些功能'）
  4. 将更改推送到分支（git push origin my-new-feature）
  5. 创建新的Pull Request

运行测试

可以使用PHPUnit运行test目录中的现有测试，以下命令

composer update --dev
cd test
../vendor/bin/phpunit
```

or if you already have PHPUnit installed globally.

```bash
cd test
phpunit
```

## Known Issues

* When using the smtp version (which is built on top of swiftmailer), any FROM names with parentheses will have the content of the parentheses stripped out. If this happens please use the web version of the library. Read more about this in [issue #27](https://github.com/sendgrid/sendgrid-php/issues/27).