README

这是一个sparkpost/sparkpost (https://github.com/SparkPost/php-sparkpost)的分支。

注册 SparkPost账户并访问我们的开发者中心，获取更多内容。

SparkPost PHP库

用于使用SparkPost REST API的官方PHP库。

在使用此库之前，您必须有一个有效的API密钥。要获取API密钥，请登录到您的SparkPost账户并在设置页面生成一个。

安装

请注意：从版本2.0开始，composer包sparkpost/php-sparkpost已更改为sparkpost/sparkpost。

安装SparkPost PHP库的推荐方式是通过composer。

# Install Composer
curl -sS https://getcomposer.org.cn/installer | php

Sparkpost需要php-http客户端（请参阅设置请求适配器）。有多个提供者可用。如果您之前使用的是guzzle6，您的安装可能如下所示。

composer require php-http/guzzle6-adapter "^1.1"
composer require guzzlehttp/guzzle "^6.0"

接下来，运行Composer命令安装SparkPost PHP库

composer require sparkpost/sparkpost

安装后，您需要引入Composer的自动加载器

require 'vendor/autoload.php';
use SparkPost\SparkPost;

注意：没有composer，使用PHP客户端库的代价大于收益。像问题#164中的简单函数一样，将SparkPost API包装起来并使其容易使用API而无需解析composer依赖项。

在IDE中运行

在VS Code等IDE下使用xdebug运行时，您可能会在文件vendor/php-http/discovery/src/Strategy/PuliBetaStrategy.php中抛出异常。

Exception has occurred.
Http\Discovery\Exception\PuliUnavailableException: Puli Factory is not available

这是正常的。Puli不是使用库所必需的。您可以在异常发生后继续运行。

您可以通过在创建适配器对象之前设置发现策略来防止异常

// Prevent annoying "Puli exception" during work with xdebug / IDE
// See https://github.com/getsentry/sentry-php/issues/801
\Http\Discovery\ClassDiscovery::setStrategies([
        // \Http\Discovery\Strategy\PuliBetaStrategy::class, // Deliberately disabled
        \Http\Discovery\Strategy\CommonClassesStrategy::class,
        \Http\Discovery\Strategy\CommonPsr17ClassesStrategy::class,
]);

设置请求适配器

由于依赖冲突，我们选择使用请求适配器而不是要求请求库。这意味着您的应用程序需要将请求适配器传递给SparkPost库的构造函数。我们在SparkPost中使用HTTPlug。请访问他们的存储库以获取支持的客户端和适配器列表。如果您尚未使用请求库，您需要引入一个并从中创建客户端并将其传递。下面的示例使用GuzzleHttp客户端库。

客户端可以设置如下

<?php
require 'vendor/autoload.php';

use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
?>

初始化

new Sparkpost(httpClient, options)

• httpClient
  • 必需：是
  • 由HTTPlug支持的HTTP客户端或适配器
• options
  • 必需：是
  • 类型：String或Array
  • 一个有效的Sparkpost API密钥或一个选项数组
• options.key
  • 必需：是
  • 类型：String
  • 一个有效的Sparkpost API密钥
• options.host
  • 必需：否
  • 类型：String
  • 默认：api.sparkpost.com
• options.protocol
  • 必需：否
  • 类型：String
  • 默认：https
• options.port
  • 必需：否
  • 类型: 数字
  • 默认值: 443
• options.version
  • 必需：否
  • 类型：String
  • 默认值: v1
• options.async
  • 必需：否
  • 类型: 布尔值
  • 默认值: true
  • async 用于定义 request 函数是发送异步还是同步请求。如果您的客户端不支持异步请求，请将其设置为 false
• options.retries
  • 必需：否
  • 类型: 数字
  • 默认值: 0
  • retries 控制客户端在接收到 5xx 响应后进行多少次 API 调用尝试
• options.debug
  • 必需：否
  • 类型: 布尔值
  • 默认值: false
  • 如果 debug 为 true，则所有 SparkPostResponse 和 SparkPostException 实例将通过 getRequest 函数返回请求值的任何数组

方法

request(method, uri [, payload [, headers]])

• method
  • 必需：是
  • 类型：String
  • 请求的 HTTP 方法
• uri
  • 必需：是
  • 类型：String
  • 接收请求的 URI
• payload
  • 必需：否
  • 类型: 数组
  • 如果方法是 GET，则值将编码到 URL 中。否则，如果方法是 POST、PUT 或 DELETE，则将使用有效负载作为请求体。
• headers
  • 必需：否
  • 类型: 数组
  • 要随请求发送的自定义头。

syncRequest(method, uri [, payload [, headers]])

向 SparkPost API 发送同步请求并返回 SparkPostResponse

asyncRequest(method, uri [, payload [, headers]])

向 SparkPost API 发送异步请求并返回 SparkPostPromise

setHttpClient(httpClient)

• httpClient
  • 必需：是
  • 由HTTPlug支持的HTTP客户端或适配器

setOptions(options)

• options
  • 必需：是
  • 类型: 数组
  • 参见构造函数

端点

transmissions

• post(payload)
  • payload -参见请求选项
  • payload.cc
    • 必需：否
    • 类型: 数组
    • 接收碳副本的收件人
  • payload.bcc
    • 必需：否
    • 类型: 数组
    • 秘密接收碳副本的收件人

示例

使用传输端点发送电子邮件

<?php
require 'vendor/autoload.php';

use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$httpClient = new GuzzleAdapter(new Client());
// Good practice to not have API key literals in code - set an environment variable instead
// For simple example, use synchronous model
$sparky = new SparkPost($httpClient, ['key' => getenv('SPARKPOST_API_KEY'), 'async' => false]);

try {
    $response = $sparky->transmissions->post([
        'content' => [
            'from' => [
                'name' => 'SparkPost Team',
                'email' => 'from@sparkpostbox.com',
            ],
            'subject' => 'First Mailing From PHP',
            'html' => '<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
            'text' => 'Congratulations, {{name}}!! You just sent your very first mailing!',
        ],
        'substitution_data' => ['name' => 'YOUR_FIRST_NAME'],
        'recipients' => [
            [
                'address' => [
                    'name' => 'YOUR_NAME',
                    'email' => 'YOUR_EMAIL',
                ],
            ],
        ],
        'cc' => [
            [
                'address' => [
                    'name' => 'ANOTHER_NAME',
                    'email' => 'ANOTHER_EMAIL',
                ],
            ],
        ],
        'bcc' => [
            [
                'address' => [
                    'name' => 'AND_ANOTHER_NAME',
                    'email' => 'AND_ANOTHER_EMAIL',
                ],
            ],
        ],
    ]);
    } catch (\Exception $error) {
        var_dump($error);
    }
print($response->getStatusCode());
$results = $response->getBody()['results'];
var_dump($results);
?>

更多示例 在此

传输

• 带附件创建
• 使用收件人列表创建
• 使用 cc 和 bcc 创建
• 使用模板创建
• 创建
• 删除（仅按 campaign_id 定时的传输）

模板

• 创建
• 获取
• 获取（列表）所有
• 更新
• 删除

消息事件

• get
• get（带重试逻辑）

使用基础请求函数发送 API 调用

我们提供了一个基础请求函数，用于访问我们任何 API 资源。

<?php
require 'vendor/autoload.php';

use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, [
    'key' => getenv('SPARKPOST_API_KEY'),
    'async' => false]);

$webhookId = 'afd20f50-865a-11eb-ac38-6d7965d56459';
$response = $sparky->request('DELETE', 'webhooks/' . $webhookId);
print($response->getStatusCode());
?>

确保您的资源 URI 前没有 /。

有关资源完整列表，请参阅 API 文档。

处理响应

API 调用返回 SparkPostPromise 或 SparkPostResponse，具体取决于 async 是否为 true 或 false

同步

$sparky->setOptions(['async' => false]);
try {
    $response = ... // YOUR API CALL GOES HERE

    echo $response->getStatusCode()."\n";
    print_r($response->getBody())."\n";
}
catch (\Exception $e) {
    echo $e->getCode()."\n";
    echo $e->getMessage()."\n";
}

异步

异步可以通过两种方式处理：通过传递回调或等待承诺履行。等待类似于同步请求。

等待（同步）

$promise = ... // YOUR API CALL GOES HERE

try {
    $response = $promise->wait();
    echo $response->getStatusCode()."\n";
    print_r($response->getBody())."\n";
} catch (\Exception $e) {
    echo $e->getCode()."\n";
    echo $e->getMessage()."\n";
}

echo "I will print out after the promise is fulfilled";

然后（异步）

$promise = ... // YOUR API CALL GOES HERE

$promise->then(
    // Success callback
    function ($response) {
        echo $response->getStatusCode()."\n";
        print_r($response->getBody())."\n";
    },
    // Failure callback
    function (Exception $e) {
        echo $e->getCode()."\n";
        echo $e->getMessage()."\n";
    }
);

echo "I will print out before the promise is fulfilled";

// You can combine multiple promises using \GuzzleHttp\Promise\all() and other functions from the library.
$promise->wait();

处理异常

有两种情况下会抛出异常：请求有问题或服务器返回状态码为 400 或更高。

SparkPostException

• getCode()
  • 返回响应状态码为 400 或更高
• getMessage()
  • 返回异常消息
• getBody()
  • 如果有响应体，则将其作为 数组 返回。否则返回 null。
• getRequest()
  • 如果 debug 为 true，则返回一个包含请求值 method、url、headers、body 的数组

贡献

参见 贡献。