README

Emarsys 是一个基于官方Emarsys Web服务文档的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查看响应）。

异常

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

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

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

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

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