README

API-PHP 库提供了一个简单易用的接口，用于访问 Get a Newsletter 的 REST API。

需求

PHP 5.5.* 或更高版本
Httpful 0.2.*

安装

如果你的项目支持 Composer，你可以在 composer.json 文件中使用以下内容

"require": {
    "getanewsletter/api-php": "0.1.1"
}

使用方法

首先创建一个 \Gan\Api 对象的实例

<?php

$token = '...';
$gan = new \Gan\Api($token);

在这里，$token 变量必须包含一个有效的 API 令牌字符串。

联系对象

\Gan\Contact 类的实例代表 API 中的联系实体。它们具有以下字段

必填字段

email - 联系的电子邮件。它也是一个 查找字段 - 更新或删除联系时必需。

可选字段

attributes - 联系的属性列表。
first_name
last_name
lists - 此联系订阅的通讯列表。

只读字段

url - 联系的资源 URL。
active - 如果联系是活跃的并且可以接收邮件，则为 true，否则为 false。
updated - 最后更改的日期。
created - 创建的日期。

检索联系

你必须创建一个 \Gan\ContactManager\ 类的实例，然后使用它的 get() 方法来检索所需的联系。

<?php

$contactManager = new \Gan\ContactManager($gan);
$contact = $contactManager->get('john.doe@example.com');

如果 API 返回 HTTP 错误，管理方法将抛出 \Gan\ApiException，因此捕获它是一个好主意。

<?php

try {
    $contact = $contactManager->get('john.doe@example.com');
} catch (\Gan\ApiException $e) {
    if ($e->response->code === 404) {
        echo 'Contact not found!';
    } else {
        echo 'API error: ' . $e;
    }
}

创建联系

<?php

$contact = new \Gan\Contact();
$contact->email = 'jane.doe@example.com';
$contact->first_name = 'Jane';

$contactManager->save($contact);

这将创建一个新的联系并将其保存。再次，当调用 save() 方法时，捕获异常是一个好主意。如果联系已存在，API 将返回错误。避免这种情况的一种方法是通过强制创建联系，覆盖现有的一个。

<?php

$contactManager->overwrite($contact);

save() 和 overwrite() 都将返回相同的联系对象，其只读字段已更新（例如，created、updated）。

<?php

$contact = $contactManager->save($contact);
echo $contact->created;

更新现有联系

<?php

// Get the contact.
$contact = $contactManager->get('john.doe@example.com');
// Change some fields.
$contact->first_name = 'John';
// Save it.
$contactManager->save($contact);

你可以通过强制执行 部分更新 来避免对 API 进行两次调用。

<?php

$contact = new \Gan\Contact();
$contact->setPersisted();
$contact->email = 'john.doe@example.com';
$contact->first_name = 'John';
$contactManager->save($contact);

在联系对象上调用 setPersisted() 将其标记为已存在且来自 API。当标记为存在的联系调用 save() 方法时，它将仅执行 部分更新，即只更新提供的字段，跳过所有 null 字段。不要忘记，email 是一个 查找字段，在更新或删除联系时必需。

删除联系

<?php

$contactManager->delete($contact);

通讯对象

\Gan\Newsletter 类的实例代表 API 中的列表。它们具有以下结构

必填字段

email - 发件人的电子邮件。
name - 列表的名称。
sender - 发件人的姓名。

可选字段

description

查找字段

hash - 列表的唯一哈希值。

只读字段

responders_count
subcribers
created
url
subscribers_count
active_subscribers_count
responders

检索、创建、更新和删除列表

列表上的 CRUD 操作与联系人上的操作没有区别

<?php

$listManager = new \Gan\NewsletterManager($gan);

// Retrieve a list.
$list = $listManager->get('hash');

// Update the list.
$list->name = 'my list';
$list = $listManager->save($list);
echo $list->updated;

// Create new list.
$new_list = new \Gan\Newsletter();
$new_list->email = 'john.doe@example.com'; // requred fields
$new_list->name = 'my new list';
$new_list->sender = 'John Doe';
$listManager->save($new_list);

// Partial update.
$list = new \Gan\Newsletter();
$list->hash = 'hash'; // lookup field
$list->name = 'updated list';
$listManager->save($list);

// Delete the list.
$listManager->delete($list);

将联系人订阅到列表

<?php

$contact->subscribeTo($list);
$contactManager->save($contact);

您还可以自动创建一个已订阅的新联系人。

<?php

$contact = new \Gan\Contact();
$contact->email = 'john.doe@example.com';
$contact->subscribeTo($list);
$contactManager->save($contact);

getanewsletter / api-php

维护者

详细信息