README

这是一个与达尔文“REST API”交互的HTTP客户端。达尔文是由https://eecsoftware.com开发的旅游运营商SaaS产品。

一些基本文档可以在以下位置找到：https://darwin11.docs.apiary.io/

需要注意的事项

• 每个请求都会返回一个"200 OK"响应，除了404 - 这可能是由于每个API端点都是一个PHP文件。无论如何，您必须检查响应负载以确定请求是否成功。此客户端负责检查负载并将请求失败转换为带有描述性错误消息的异常。
• 所有请求都必须提供正文。认证负载作为请求正文的一部分发送。
• 似乎只接受POST请求，因此如果某个方法被记录为GET请求，那么它可能不是。
• 字段名称是大小写敏感的。这最初让我困惑，因为字段被错误地记录了大小写。
• 文档经常是不正确或不完整的。
• 大多数响应负载是array<string, string> - null数组成员通常是空字符串，int数组成员通常是数字字符串等，因此需要进行很多类型转换。这不是一个固定的规则，通常响应负载的类型是一致的。
• 远程应用程序将未知日期存储为int零，这意味着未知日期在负载中返回为1970-01-01。这实际上意味着特定日期等于"未知"，您必须希望您的客户实际上不是在这一天出生的。

要求 & 安装

因为此库使用了azjezz/psl，因此需要bcmath扩展。在composer.json中列出了所有依赖关系要求。

仅支持通过composer进行安装

composer require conservationafrica/darwin-client

用法

一般来说，您应该在\Darwin\Client接口上使用类型提示，以便在测试中模拟客户端。

类型推断相当不错，不是100%，但足够接近。您应该使用Psalm或PHPStan。它会帮助您！

所有异常都实现了公共标记接口\Darwin\DarwinError。将客户端的所有调用包裹在类似于

use Darwin\Client;
use Darwin\DarwinError;

assert($client instanceof Client);

try {
    $customer = $client->findClientByEmailAddress('me@example.com');
} catch (DarwinError) {
    // Handle exception appropriately
}

printf('Hi %s 👋', $customer->firstName);

具体客户端构造

您需要使用您的DIC构造具体客户端，有几个构造函数依赖项

<?php

declare(strict_types=1);

use Darwin\HttpClient;
use Http\Client\Curl\Client as CurlClient;
use Laminas\Diactoros\RequestFactory;
use Laminas\Diactoros\StreamFactory;
use Lcobucci\Clock\SystemClock;

$client = new HttpClient(
    'https://your-subdomain.eecsoftware.com',
    '/AJAX/', // <- Whilst this is probably the same for all installations, you still need to specify it.
    'Some shared secret', // <- This is provided by the vendor
    99, // <- The company Identifier, supplied by the vendor
    new SystemClock(new DateTimeZone('UTC')), // Some Psr\Clock\ClockInterface implementation
    new CurlClient(), // <- Any Psr 18 compliant HTTP client
    new RequestFactory(), // <- Any Psr 17 compliant request factory
    new StreamFactory(), // <- Any Psr 17 compliant stream factory
);

运行测试

有两个测试套件，Integration和Unit

要在远程服务器上运行集成测试，您需要声明环境变量

• API_URL - 这是方案和主机，例如https://example.com - 测试套件中默认基本路径/AJAX/是硬编码的。
• API_SECRET - 这是用于生成达尔文所需的hash_hmac签名的共享密钥。
• COMPANY_ID - 达尔文提供的整数公司ID。

远程API方法详细信息及注意事项

getClient方法

当有多个“客户”使用达尔文中记录的相同电子邮件地址时，此方法将返回众多客户中最新的一个。这里的“最新”定义为按插入日期降序，或按自增ID降序。

相反，如果你调用 createClient，数据将被应用到最旧的匹配客户，即按插入日期升序。

createClient 方法 （这是一个更新插入操作）

正如所述，此方法是一个更新插入操作，但是，任何省略的字段将擦除现有数据，因此不要将此方法视为补丁。例如，在第一个请求中发送 {"firstname": "foo", "lastname": "bar"}，然后在第二个请求中发送 {"firstname": "new"}，将得到一个将 lastname 设置为空字符串的客户记录。

• dateofbirth 将将ISO日期（如 2001-07-04）解释为2001年7月4日。
• country 只能是任意字符串 - UI中可用的下拉列表没有相应的API方法，实际上将值设置为一个模糊字符串，在这里提供ISO国家代码只是为了使UI能够将国家代码显示给用户。

首选联系方式

文档说明值必须是“电子邮件”或“电话”，但你可以为 preferredcontactmethod 字段提供一个整数，该整数与以下之一匹配

• 1 = 主要电子邮件
• 2 = 次要电子邮件
• 3 = 家庭电话
• 4 = 工作电话
• 5 = 手机
• 6 = Skype
• 7 = Facebook
• 8 = 邮寄

getCountryList 方法

此端点对于识别与客户相关的国家没有用。它将只返回几个国家 - 由客户定义的国家。

createEnquiry 方法

一般来说，你可以使用此方法发送任何旧垃圾数据，只要你遵守在 ClientInterface::EnquiryPayload psalm类型中概述的规范。

6个“感兴趣国家”字段必须对应一个国家标识符，这并不是很有帮助，（这里可能更合理地选择ISO国家代码）。不提供有效的标识符将保证导致500错误。