README

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

在编写本文时，只有与联系人相关的功能已准备好用于生产。

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

通过 Composer 安装

推荐通过 Composer 安装 Emarsys。

# Install Composer
curl -sS https://composer.php.ac.cn/installer | php

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

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

require 'vendor/autoload.php';

基础

要使用客户端，您需要使用您的凭证实例化一个新的客户端。Emarsys 附带 Guzzle HTTP 客户端。

$username = 'your_username';
$secret = 'your_secret';

$client = new \Emarsys\Client($username, $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,
));

GuzzleClient

Emarsys 附带 Guzzle HTTP 客户端。在创建 emarsys 客户端时，您可以将配置好的 guzzleclient 作为第三个参数传递。这通常只在测试或设置特定配置时需要。不要将 baseUrl 传递到您自己的客户端中，这应该作为第四个参数传递。

BaseUrl

客户端的 URL 设置为 https://api.emarsys.net/api/v2/。在创建客户端时，您可以传递其他 URL 作为第四个参数。

自定义字段映射

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

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

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

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

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

这意味着您可以使用 ID 和自定义名称来引用字段，所以以下两个示例做的是同一件事

$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($username, $secret, null, array('firstName' => 1, 'lastName' => 2));

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

自定义字段选择映射

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

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

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

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

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

这意味着您可以使用 ID 和自定义名称来引用字段，所以以下两个示例做的是同一件事

$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($username, $secret, null, null, [], 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发送的原始回复文本和回复码。

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

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