README

一个PHP库，实现了Campaign Monitor API的完整功能。

安装

Composer

如果你使用Composer，可以从项目的根目录运行以下命令

composer require campaignmonitor/createsend-php

或者将campaignmonitor/createsend-php添加到你的composer.json文件中

{
    "require": {
        "campaignmonitor/createsend-php": "{version}"
    }
}

然后运行

composer update

手动安装

否则你可以简单地下载这个库并将其包含在你的项目中。

安装库后，只需包含相关的API类，如下所示

require_once 'csrest_campaigns.php'

认证

Campaign Monitor API支持使用OAuth或API密钥进行认证。

使用OAuth

根据你正在开发的环境，你可能希望使用PHP OAuth库为你的用户获取访问令牌。如果你不使用OAuth库，你需要按照Campaign Monitor API 文档中的说明为你的用户获取访问令牌。此包提供了一些功能来帮助你完成此操作，如下所述。你也可以参考这个示例应用程序，该应用程序使用Slim实现，但可以轻松地用于任何PHP框架。

你的应用程序应该首先将用户重定向到Campaign Monitor授权URL，在那里他们有机会批准你的应用程序访问他们的Campaign Monitor账户。你可以通过使用CS_REST_General::authorize_url()方法来获取此授权URL，如下所示

require_once 'csrest_general.php';

$authorize_url = CS_REST_General::authorize_url(
    'Client ID for your application',
    'Redirect URI for your application',
    'The permission level your application requires',
    'Optional state data to be included'
);
# Redirect your users to $authorize_url.

如果你的用户批准了你的应用程序，他们将被重定向到你指定的redirect_uri，该URL将包括一个code参数，以及可选的state参数。你的应用程序应该实现一个处理程序，可以使用CS_REST_General::exchange_token()将其传递的代码交换为访问令牌，如下所示

require_once 'csrest_general.php';

$result = CS_REST_General::exchange_token(
    'Client ID for your application',
    'Client Secret for your application',
    'Redirect URI for your application',
    'A unique code for your user' # Get the code parameter from the query string
);

if ($result->was_successful()) {
    $access_token = $result->response->access_token;
    $expires_in = $result->response->expires_in;
    $refresh_token = $result->response->refresh_token;
    # Save $access_token, $expires_in, and $refresh_token.
} else {
    echo 'An error occurred:\n';
    echo $result->response->error.': '.$result->response->error_description."\n";
    # Handle error...
}

此时，你有了用户的一个访问令牌和一个刷新令牌，你应该将其存储在一个方便的地方，以便你的应用程序在用户想要进行未来的Campaign Monitor API调用时可以查找这些值。

一旦你有了用户的一个访问令牌和一个刷新令牌，你可以进行认证并执行进一步的API调用，如下所示

require_once 'csrest_general.php';

$auth = array(
    'access_token' => 'your access token',
    'refresh_token' => 'your refresh_token');
$wrap = new CS_REST_General($auth);

$result = $wrap->get_clients();
var_dump($result->response);

所有OAuth令牌都有一个过期时间，并且可以使用相应的刷新令牌进行更新。如果在尝试进行API调用时访问令牌过期，你会收到一个错误响应，因此你的代码应该处理这种情况。以下是一个示例，说明你可以如何做

require_once 'csrest_general.php';

$auth = array(
    'access_token' => 'your access token',
    'refresh_token' => 'your refresh token'
);
$wrap = new CS_REST_General($auth);
$result = $wrap->get_clients();
if (!$result->was_successful()) {
    # If you receive '121: Expired OAuth Token', refresh the access token
    if ($result->response->Code == 121) {
        list($new_access_token, $new_expires_in, $new_refresh_token) = 
            $wrap->refresh_token();
        # Save $new_access_token, $new_expires_in, and $new_refresh_token
    }
    # Make the call again
    $result = $wrap->get_clients();
}
var_dump($result->response);

使用API密钥

require_once 'csrest_general.php';

$auth = array('api_key' => 'your API key');
$wrap = new CS_REST_General($auth);

$result = $wrap->get_clients();
var_dump($result->response);

API调用超时

您可以在 createsend-php\class\transport.php 文件的第 11 行设置本地 API 调用超时时间，变量为 CS_REST_CALL_TIMEOUT。当前默认值为 120 秒。

示例

创建或访问所有资源的示例可以在 samples 目录中找到。这些示例可以作为您自己应用程序的基础，并提供每个 API 调用预期输入的概述。

每个调用的输入和输出的进一步文档可以在每个 csrest_*.php 文件中的文档中找到，或者简单地通过检查每个提供的示例中的 var_dump 结果。

贡献

请查看贡献此存储库的指南。

发布

请查看发布此库的说明。