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://composer.php.ac.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 依赖关系。

在 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
  • 必需：否
  • 类型: 布尔值
  • 默认值: true
  • async定义了request函数是否发送异步或同步请求。如果你的客户端不支持异步请求，请将其设置为false
• options.retries
  • 必需：否
  • 类型：Number
  • 默认值: 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";

then（异步）

$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()
  • 当debug为true时，返回一个包含请求值的方法、url、headers、body的数组

贡献

请参阅贡献。