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 会话支持以进行身份验证。请参阅 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，但现代PHP版本的优点远远超过了过时的向后兼容性观念。是时候升级了。