README

PHP 对 Constant Contact V3 API 的面向对象封装。

PHPFUI/ConstantContact 是一个 现代 PHP 库，它跟踪 Constant Contact API 的最新更改。

PHPFUI/ConstantContact 从 Constant Contact 文档中读取 YAML 文件，并直接从 YAML 文件生成 PHP 类。该库每晚自动更新。这意味着该库始终与最新更改保持同步。有关详细信息，请参阅版本控制部分。

安装

由于此库在 Constant Contact 更新其 API 时会不断更新，因此最好将 Composer 版本约束从 '^' 更改为 '>=', 例如

"phpfui/constantcontact": "^22.3",

应更改为

"phpfui/constantcontact": ">=22.3",

需求

此库需要 PHP Session 支持进行身份验证。请参阅 PHP 手册 和 一篇优秀的最佳实践文章。您可以通过指定 setSessionCallback 的回调来提供自己的会话管理。

命名空间

此库将 Constant Contact API 标准化为现代 PHP 类标准。所有端点都以大写字母开头。下划线被删除，并随后跟上一个大写字母。每个端点都是一个具有与标准 REST 方法（例如 put、post、delete、put 等）匹配的方法的类。这些方法接受与 Constant Contact YAML API 中指定的名称匹配的必需和可选参数。此外，此库支持 API 中所有类型的定义。请参阅以下内容。

由于 Constant Contact API 设计者在命名规范上的错误，一些端点在返回所有对象的端点和仅与一个对象一起工作的端点之间重复。通常，这通过在单个对象上的 CRUD 类型操作使用名词的单数形式来处理，而复数名词形式返回对象列表。此库遵循正确的命名约定（单数名词用于 CRUD 和复数名词用于集合），而不是 Constant Contact 命名约定。

定义

此 Constant Contact API 定义了与 API 交互的所有类型的对象。它们在 PHPFUI\ConstantContact\Definition 命名空间中定义。只允许访问有效字段。类型在 PHP 的最佳能力范围内得到全面验证。字符串的长度强制执行最小和最大长度。

授权后使用（见下文）

// Create a client
$client = new \PHPFUI\ConstantContact\Client($apiKey, $secret, $redirectURI);
// Set access and refresh tokens on client
$client->accessToken = $accessTokenFromDatabase;
$client->refreshToken = $refreshTokenFromDatabase;
// Refresh the tokens.  This should be done on a regular (daily) basis so the token does not expire.
$client->refreshToken();
// save $client->accessToken and $client->refreshToken to database.

// $client is now ready to use
$listEndPoint = new \PHPFUI\ConstantContact\V3\ContactLists($client);
$lists = $listEndPoint->get();
do {
  print_r($lists);
  $lists = $listEndPoint->next();
} while ($lists);

Constant Contact 设置

为了使用这个库，您需要正确设置Constant Contact。请访问 Constant Contact API 并创建一个应用程序。获取一个 API密钥 和 密钥，并将其保存用于 \PHPFUI\ConstantContact\Client 构造函数。您还需要设置并添加一个 重定向URI。如果您想手动授权，可以使用 https://，但建议允许用户直接授权。重定向URI将接收到授权应用所需的代码，然后存储生成的访问令牌和刷新令牌。您还应提供您网站应用的logo URL。当用户认证应用时，将显示此logo。如果他们尚未这样做，则需要登录Constant Contact。填写其他适当信息，但仅用于信息目的。

授权控制流程

您需要设置一个网页，让用户可以输入 API密钥 和 密钥。如果API返回错误，表示未授权，您应提供一个 “授权” 按钮。这允许用户控制授权过程。授权需要交互式进行。用户必须登录到Constant Contact并授权应用。完成此操作后，应用可以在后台运行，每天刷新令牌，只要密钥没有更改，就不需要重新授权。更改密钥需要重新授权。

授权控制流程如下

1. 创建客户端并重定向到授权URL

$redirectURI = 'http://yourdomain/php_script_in_step2.php';
$client = new \PHPFUI\ConstantContact\Client($apiKey, $secret, $redirectURI);
// set any scopes here, defaults to all scopes. Your user will need to accept what ever scopes you specify.
// $client->setScopes(['contact_data', 'campaign_data']);
\header('location: ' . $client->getAuthorizationURL());

如上所述，将要求用户授权应用指定的范围。默认为所有范围，但您可以在构造客户端并授权之前指定不同的范围。

2. 从 $redirectURI 获取发送的代码

$client = new \PHPFUI\ConstantContact\Client($apiKey, $secret, $redirectURI);
$client->acquireAccessToken($_GET);
// Save $client->accessToken and $client->refreshToken to the database
// redirect back to your businesss logic (Step 3)

您现在已根据您请求的范围获得了访问API的授权。

3. 在您的代码中使用

$client = new \PHPFUI\ConstantContact\Client($apiKey, $secret, $redirectURI);
$client->accessToken = $accessTokenFromDatabase;
$client->refreshToken = $refreshTokenFromDatabase;
$listEndPoint = new \PHPFUI\ConstantContact\V3\ContactLists($client);
$lists = $listEndPoint->get();
do {
  print_r($lists);
  $lists = $listEndPoint->next();
} while ($lists);

您现在可以使用您请求的范围访问API。

4. 定期刷新令牌

$client->refreshToken();
// save $client->accessToken and $client->refreshToken to database.

令牌将过期，除非您刷新令牌，否则用户需要重新授权您的应用。您应该定期刷新令牌以避免重新授权。

版本控制

由于 Constant Contact API 不断更新，此库将基于日历版本的版本控制方案跟踪所有更新。主要版本将是更新发布的年份的最后两位数字。次要版本将是发布的月份。任何错误修复将是补丁版本。因此，V21.8.0将是2021年8月的第一版，V21.8.1将是V21.8的错误修复版本。所有错误修复都将包含在后续版本中，因此V21.9.0将包含V21.8版本的所有修复。YAML更改每晚跟踪，并自动生成新版本。一个月内的多个YAML更改将被跟踪为补丁版本。

完整类文档

PHPFUI/InstaDoc

许可证

PHPFUI/ConstantContact 在MIT许可证下分发。

PHP版本

此库仅支持PHP 8.0及以上版本的PHP。虽然我们希望支持从明末的PHP，但现代PHP版本的优势远远超过向后兼容的陈旧观念。是时候升级了。