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将接收一个代码，用于授权应用程序，然后存储生成的访问令牌和刷新令牌。您还应该提供您网站应用程序标志的URL。当用户验证应用程序时，将显示此标志。如果用户尚未登录，则需要登录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.
\header('location: ' . $client->getAuthorizationURL());

上述操作将要求用户授权应用程序访问您指定的作用域。默认情况下，所有作用域都可用，但您可以在构造客户端并在授权之前指定不同的作用域。

2. 从$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的修复。YAML更改每晚跟踪，并自动生成新版本。一个月内多次YAML更改将作为补丁版本跟踪。

完整类文档

PHPFUI/InstaDoc

许可证

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

PHP版本

此库仅支持PHP 8.0及更高版本。虽然我们愿意支持明末时期的PHP，但现代PHP版本的优势远大于过时的向后兼容性观念。是时候升级了。