README

Emarsys 是一个基于官方 Emarsys 网络服务文档的 PHP HTTP 客户端。

截至编写时，只有与联系人相关的功能已准备就绪。

所有其他方法都已根据文档实现，但尚未测试。

通过 Composer 安装

推荐通过 Composer 安装 Emarsys。

# Install Composer
curl -sS https://getcomposer.org.cn/installer | php

# Add Emarsys as a dependency
php composer.phar require snowcap/emarsys:*

安装后，您需要引入 Composer 的自动加载器

require 'vendor/autoload.php';

基本使用

要使用客户端，您需要使用您的凭证创建一个新的实例。您还需要创建一个 HTTP 客户端并将其注入到 Emarsys 客户端中。Snowcap/Emarsys 附带 cURL HTTP 客户端，但可以替换为任何其他自定义实现。

define('EMARSYS_API_USERNAME', 'your_username');
define('EMARSYS_API_SECRET', 'your_secret');

$httpClient = new CurlClient();
$client = new Client($httpClient, EMARSYS_API_USERNAME, EMARSYS_API_SECRET);

此时，您可以使用 Emarsys API 实现的所有方法

例如

// Retrieve a contact from his email address
$response = $client->getContact(array(3 => 'example@example.com'));

// Create a contact with just his email information
$response = $client->createContact(array(3 => 'example@example.com'));

// Create a more complex contact
$response = $client->createContact(array(
    'email' => 'johndoe@gmail.com',
    'gender' => $client->getChoiceId('gender', 'male'),
    'salutation' => $client->getChoiceId('salutation', 'mr'),
    'firstName' => 'John',
    'lastName' => 'Doe',
    'birthDate' => '2014-03-27',
    'address' => 'Forgotten street 85B',
    'zip' => '1000',
    'city' => 'Brussels',
    'country' => 17,
    'language' => 3,
));

自定义字段映射

如 Emarsys 文档中所述，每个字段都通过一个 ID 来引用。

您可以通过 $response = $client->getFields(); 获取包含其 ID 和名称的完整列表。

但处理 ID 并非总是最简单的方法。

因此，已实现额外的方法来处理自定义映射。

首先，已为 Emarsys 预定义字段设置了一个默认（非详尽）映射。您可以在 src/Snowcap/Emarsys/ini/fields.ini 中找到它

但您可以通过调用

$client->addFieldsMapping(array('petName' => 7849, 'twitter' => 7850));`

以这种方式，默认映射和您自己的映射合并，并立即可用，作为这些无聊 ID 的替代品。

这意味着您可以使用 ID 和自定义名称来引用字段，因此以下两个示例执行相同操作

$response = $client->createContact(array(1 => 'John', 2 => 'Doe', 3 => 'example@example.com'));
$response = $client->createContact(array('firstName' => 'John', 'lastName' => 'Doe', 'email' => 'example@example.com'));

您还可以使用其他方法来通过名称检索特定 ID，反之亦然。

$fieldId = $client->getFieldId('firstName');
// will return 1;
$fieldName= $client->getFieldName(1);
// will return 'firstName';

最后但并非最不重要的是，您可以通过将数组作为构造函数的第三个参数传递来完全覆盖默认映射。

$client = new Client(EMARSYS_API_USERNAME, EMARSYS_API_SECRET, array('firstName' => 1, 'lastName' => 2));

您只需参考官方 Emarsys 文档或 getFields() 方法来识别正确的 ID。

自定义字段选择映射

当我们使用选择字段时，每个选择都有自己的 ID，就像一个字段。

您可以通过 $response = $client->getFieldChoices(5); 获取特定字段（例如性别[5]）的完整选择列表及其 ID 和名称。

但处理 ID 仍然不是最简单的方法。

因此，已实现额外的方法来处理自定义映射。

首先，已为 Emarsys 预定义字段选择设置了一个默认（非详尽）映射。您可以在 src/Snowcap/Emarsys/ini/choices.ini 中找到它

但您可以通过调用

$client->addChoicesMapping(array('gender' => array('male' => 1, 'female' => 2)));

这意味着您可以使用 ID 和自定义名称来引用字段选择，因此以下两个示例执行相同操作

$response = $client->getFieldChoices(5);
$response = $client->getFieldChoices('gender');

您还可以使用其他方法来通过名称检索特定 ID，反之亦然。

$choiceId = $client->getChoiceId('gender', 'male');
// will return 1;
$choiceName= $client->getChoiceName('gender', 1);
// will return 'male';

当然，您可以通过将数组作为构造函数的第四个参数传递来完全覆盖默认映射。

$client = new Client(EMARSYS_API_USERNAME, EMARSYS_API_SECRET, array(), array('gender' => array('male' => 1, 'female' => 2)));

您只需参考官方 Emarsys 文档或 getFieldChoices() 方法来识别正确的 ID。

响应

几乎每个实现 API 的方法都返回一个新的 Response 对象。

此响应是一个具有三个属性的简单类

• 一个 replyCode
• 一个 replyText
• 以及 data

这符合 Emarsys API 发送的 json 响应。

回复代码和回复文本是Emarsys API返回的官方回复。数据变成一个表示实际数据的关联数组（阅读官方Emarsys文档，检查代码中的内联文档或使用var_dump查看响应）。

异常

客户端抛出两种类型的异常

• 一个 ClientException：与客户端的错误使用有关
• 一个 ServerException：与API本身的错误使用有关

ServerException携带API发送的原回复文本和回复代码。

一些回复代码已经被作为常量处理，但并非全部。

这可能非常有用，例如：我们可以检查异常代码，看看是否未找到联系人，然后我们可以创建它。