README

ConvertKit PHP SDK 为使用 PHP 编写的应用程序提供了方便的 ConvertKit API 访问。

它包含了一组预定义的方法来与 API 交互。

版本指南

有关升级到 v2 SDK 的更改，请参阅本指南。

Composer

您可以通过 Composer 安装此 PHP SDK。运行以下命令：

composer require convertkit/convertkitapi

要使用 PHP SDK，请使用 Composer 的自动加载。

require_once 'vendor/autoload.php';

依赖关系

PHP SDK 需要以下扩展才能正常工作：

curl，尽管如果您愿意，也可以使用您自己的非 cURL 客户端
json
mbstring（多字节字符串）

如果您使用 Composer，这些依赖项应自动处理。

入门指南

2.x（v4 API，OAuth，PHP 8.0+）

首先，在 https://app.convertkit.com/account_settings/advanced_settings 的“OAuth 应用程序”部分注册您的 OAuth 应用程序。

使用提供的客户端 ID 和密钥，将用户重定向到 ConvertKit 以授予您的应用程序访问其 ConvertKit 账户的权限。

// Require the autoloader (if you're using a PHP framework, this may already be done for you).
require_once 'vendor/autoload.php';

// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API(
    clientID: '<your_oauth_client_id>',
    clientSecret: '<your_oauth_client_secret>'
);

// Redirect to begin the OAuth process.
header('Location: '.$api->get_oauth_url('<your_redirect_uri>'));

一旦用户授予您的应用程序对其 ConvertKit 账户的访问权限，他们将被重定向到您的重定向 URI，并带有授权代码。例如

your-redirect-uri?code=<auth_code>

在此阶段，您的应用程序需要用授权代码交换访问令牌和刷新令牌。

$result = $api->get_access_token(
    authCode: '<auth_code>',
    redirectURI: '<your_redirect_uri>'
);

$result 是一个数组，包含以下内容：

access_token：访问令牌，用于向 API 发送经过身份验证的请求
refresh_token：刷新令牌，用于在当前访问令牌过期后获取新的访问令牌
created_at：访问令牌创建的时间
expires_in：created_at 之后的秒数，表示访问令牌将过期

一旦您有了访问令牌，请使用它重新初始化 API 类

// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API(
    clientID: '<your_oauth_client_id>',
    clientSecret: '<your_oauth_client_secret>',
    accessToken: '<your_access_token>'
);

要刷新访问令牌

$result = $api->refresh_token(
    refreshToken: '<your_refresh_token>',
    redirectURI: '<your_redirect_uri>'
);

$result 是一个数组，包含以下内容：

access_token：访问令牌，用于向 API 发送经过身份验证的请求
refresh_token：刷新令牌，用于在当前访问令牌过期后获取新的访问令牌
created_at：访问令牌创建的时间
expires_in：created_at 之后的秒数，表示访问令牌将过期

一旦您刷新了访问令牌（即获取了新的访问令牌），请使用它重新初始化 API 类

// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API(
    clientID: '<your_oauth_client_id>',
    clientSecret: '<your_oauth_client_secret>',
    accessToken: '<your_new_access_token>'
);

然后可以执行 API 请求

$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@convertkit.com');

要确定是否创建了一个新的实体/关系，或者更新了现有的实体/关系，请检查最后请求的 HTTP 状态码

$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@convertkit.com');
$code = $api->getResponseInterface()->getStatusCode(); // 200 OK if e.g. a subscriber already added to the specified form, 201 Created if the subscriber added to the specified form for the first time.

如果需要，可以获取 PSR-7 响应并进一步检查，例如检查是否存在标题

$result = $api->add_subscriber_to_form(12345, 'joe.bloggs@convertkit.com');
$api->getResponseInterface()->hasHeader('Content-Length'); // Check if the last API request included a `Content-Length` header

1.x（v3 API，API 密钥和密钥，PHP 7.4+）

在此处获取您的 ConvertKit API 密钥和 API 密钥，并在您的应用程序中设置。

// Require the autoloader (if you're using a PHP framework, this may already be done for you).
require_once 'vendor/autoload.php';

// Initialize the API class.
$api = new \ConvertKit_API\ConvertKit_API('<your_public_api_key>', '<your_secret_api_key>');

处理错误

ConvertKit PHP SDK 使用 Guzzle 进行所有 HTTP API 请求。错误将以 Guzzle 的 ClientException（对于 4xx 错误）或 ServerException（对于 5xx 错误）的形式抛出。

try {
    $forms = $api->add_subscriber_to_form('invalid-form-id');
} catch (GuzzleHttp\Exception\ClientException $e) {
    // Handle 4xx client errors.
    die($e->getMessage());
} catch (GuzzleHttp\Exception\ServerException $e) {
    // Handle 5xx server errors.
    die($e->getMessage());
}

在抛出 ClientException 时，可以获取 API 的响应以获取更详细的错误消息。

// Errors will be thrown as Guzzle's ClientException or ServerException.
try {
    $forms = $api->form_subscribe('invalid-form-id');
} catch (GuzzleHttp\Exception\ClientException $e) {
    // Handle 4xx client errors.
    // For ClientException, it's possible to inspect the API's JSON response
    // to output an error or handle it accordingly.
    $error = json_decode($e->getResponse()->getBody()->getContents());
    die($error->message); // e.g. "Entity not found".
} catch (GuzzleHttp\Exception\ServerException $e) {
    // Handle 5xx server errors.
    die($e->getMessage());
}

文档

请参阅PHP SDK 文档

贡献

请参阅我们的贡献指南以设置您的开发环境、测试和提交PR。

关于ConvertKit，请参考部署指南了解如何发布新版本。

convertkit / convertkitapi

维护者

详细信息