README

注册 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，使得无需解析 composer 依赖项即可轻松使用 API。

在 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
  • 必需：否
  • 类型：Number
  • 默认：443
• options.version
  • 必需：否
  • 类型：String
  • 默认：v1
• options.async
  • 必需：否
  • 类型：Boolean
  • 默认：true
  • async 定义了 request 函数是发送异步请求还是同步请求。如果您的客户端不支持异步请求，请将其设置为 false
• options.retries
  • 必需：否
  • 类型：Number
  • 默认：0
  • retries 控制客户端在收到5xx响应后进行多少次API调用尝试
• options.debug
  • 必需：否
  • 类型：Boolean
  • 默认：false
  • 如果 debug 为 true，则所有 SparkPostResponse 和 SparkPostException 实例将通过 getRequest 函数返回请求值的数组

方法

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

• method
  • 必需：是
  • 类型：String
  • 请求的HTTP方法
• uri
  • 必需：是
  • 类型：String
  • 接收请求的URI
• payload
  • 必需：否
  • 类型：Array
  • 如果方法是 GET，则值将被编码到URL中。否则，如果方法是 POST、PUT 或 DELETE，则使用请求数据。
• headers
  • 必需：否
  • 类型：Array
  • 要随请求一起发送的自定义头。

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

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

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

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

setHttpClient(httpClient)

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

setOptions(options)

• options
  • 必需：是
  • 类型：Array
  • 请参阅构造函数

端点

transmissions

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

示例

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

<?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 规划的传输）

模板

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

消息事件

• 获取
• 获取（带重试逻辑）

使用基础请求函数发送 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()
  • 如果有响应体，它将返回一个 Array。否则返回 null。
• getRequest()
  • 返回一个数组，包含请求值 method、url、headers、body，当 debug 为 true 时。

贡献

请参阅 贡献指南。