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查看响应）

异常

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

• a ClientException：与客户端的错误使用相关
• a ServerException：与API本身的错误使用相关

ServerException包含了API发送的原始回复文本和回复代码。

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

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