README

此包提供了基于模型的 Newsletter2Go API 实现。它旨在使复杂的文档变得不必要。凭借其清晰的结构和广泛的 PHPDoc，它非常易于使用。

安装

通过 Composer

$ composer require richardhj/newsletter2go-api

用法

获取和修改

如果您想通过 API 获取项目，可能有一个静态函数可供使用。示例

$users = Richardhj\Newsletter2Go\Api\Model\NewsletterUser::findAll(null, $apiCredentials);

// Use a PHPDoc comment and profit from auto suggestion
/** @var NewsletterUser $user */
foreach ($users as $user) {
    // What's about naming all users "Doe"?
    $user->setLastName('Doe');
    // Save the user (via the API of course)
    $user->save();
    
    // $data contains all data fetched for this item
    $data = $user->getData();
}

$recipients = Richardhj\Newsletter2Go\Api\Model\NewsletterRecipient::findByListAndGroup('abc123', 'xyz987', null, $apiCredentials);
var_dump($recipients);

foreach ($recipients as $recipient) {
    $recipient->addToGroup('xyz345');
    $recipient->removeFromGroup('asdf12');
}

API 凭据

ApiCredentials 是 API 通信的必填项。首先，您需要可以在 Newsletter2Go 后端找到的 auth_key。auth_key 对于公司的所有账户都是相同的。此外，您还需要用户的 username 和 password 或用户的 refresh_token。

如果您更愿意在您的应用程序中使用和保存 refresh_token 而不是使用用户名和密码，您仍然需要使用用户名和密码进行初始 API 授权调用。请参阅相应的 OAuth 提供者的 手册，了解如何获取 refresh_token。

// Use the ApiCredentialsFactory
$apiCredentials = ApiCredentialsFactory::createFromUsernameAndPassword('secret_auth_token', 'user@example.org', 'open_sesame');
$apiCredentials = ApiCredentialsFactory::createFromRefreshToken('secret_auth_token', 'secret_users_refresh_token');
// Or simply use ::create()
$apiCredentials = ApiCredentialsFactory::create('secret_auth_token', 'secret_users_refresh_token');

获取参数

当从 API 获取集合时，您可以提供 GetParameters 实例。获取参数允许您过滤、限制等要返回的项目集合。示例

$getParams = new Richardhj\Newsletter2Go\Api\Tool\GetParameters();
$getParams
    ->setExpand(true)
    ->setFilter('email=like="%@example.org"')
    ->setOffset(2)
    ->setLimit(1);

$recipients = Richardhj\Newsletter2Go\Api\Model\NewsletterRecipient::findByListAndGroup('abc123', 'xyz987', $getParams, $apiCredentials);
var_dump($recipients);

创建

如果您想通过 API 创建项目，可以这样操作。示例

$recipient = new Richardhj\Newsletter2Go\Api\Model\NewsletterRecipient();
$recipient->setApiCredentials($apiCredentials);
$recipient
    ->setListId('abc123')
    ->setFirstName('John')
    ->setLastName('Doe')
    ->setEmail('doe@example.org')
    ->setGender('m');

// Good to have an id, otherwise the email address will be the primary key and you will not be able to change the email address of a recipient properly
$recipient->setId('xyz123');

// Update an existing recipient (when id given or email address known in Newsletter2Go) or create a new recipient
$recipient->save();

删除

对于实现了 Newsletter2Go\Api\Model\ModelDeletableInterface 的模型，可用 delete()。示例

$groups = Newsletter2Go\Api\Model\NewsletterGroup::findByList('abc123', $getParams, $credentials);

/** @var NewsletterGroup $group */
foreach ($groups as $group) {
    $group->delete();
}

官方 API 文档

访问 官方 API 文档 以获取参考。

许可证

GNU Lesser General Public License (LGPL)。