README

#myallocator-pms-php

Myallocator PMS PHP SDK (JSON & XML)。物业管理系统 (PMS) 可以使用此 SDK 快速可靠地集成 myallocator API，以为其客户提供分销服务。

注意，这不是 BuildToUs PHP SDK 用于 OTA。BuildToUs PHP SDK 可在 https://github.com/MyAllocator/myallocator-ota-php 找到

Myallocator API 版本：201408

Myallocator PHP SDK 文档 [http://myallocator.github.io/myallocator-pms-php-docs/]

Myallocator API 文档 [http://myallocator.github.io/apidocs/]

Myallocator API 集成指南 [https://docs.google.com/document/d/1_OuI0Z6rTkkuA9xxlJUvhXlazJ9w_iqsp1QzIj4gb2U/edit?usp=sharing]

Myallocator [https://www.myallocator.com/]

Myallocator 开发支持 [devhelp@myallocator.com]

需求

PHP 5.3.2 及以上版本。

文档

请参阅 http://myallocator.github.io/myallocator-pms-php-docs/ 获取完整和最新的 SDK 文档。

Composer

您可以通过 composer 安装。将以下内容添加到项目中的 composer.json 文件。

{
    "require": {
        "myallocator/myallocator-php-sdk": "1.*"
    }
}

然后通过以下方式安装：

composer.phar install

要使用绑定，可以使用 Composer 的自动加载 [https://getcomposer.org.cn/doc/00-intro.md#autoloading]

require_once('vendor/autoload.php');

或手动

require_once('/path/to/vendor/MyAllocator/myallocator-php-sdk/src/MyAllocator.php');

手动安装

获取 SDK 的最新版本

git clone https://github.com/MyAllocator/myallocator-pms-php.git

要使用绑定，将以下内容添加到 PHP 脚本中

require_once('/path/to/myallocator-php-sdk/src/MyAllocator.php');

入门

使用 composer 安装的安装和用法示例

root@nate:/var/www# mkdir project
root@nate:/var/www# cd project/
root@nate:/var/www/project# echo '{"require": {"myallocator/myallocator-php-sdk": "1.*"}}' > composer.json
root@nate:/var/www/project# composer install
Loading composer repositories with package information
Installing dependencies (including require-dev)
  - Installing myallocator/myallocator-php-sdk (1.2.1)
    Downloading: 100%         
Writing lock file
Generating autoload files
root@nate:/var/www/project# cp vendor/myallocator/myallocator-php-sdk/src/example_autoload.php .
root@nate:/var/www/project# v example_autoload.php

将 example_autoload.php 中的第 33 行的 require_once 自动加载编辑为

require_once(dirname(__FILE__) . '/vendor/autoload.php');

运行 HelloWorld ping myallocator

root@nate:/var/www/project# php example_autoload.php
{"Auth" : "true", hello" : "world"}

使用手动安装的安装和用法示例

root@nate:/var/www# mkdir -p project/lib
root@nate:/var/www# cd project/lib/
root@nate:/var/www/project/lib# git clone https://github.com/MyAllocator/myallocator-pms-php.git
Cloning into 'myallocator-pms-php'...
remote: Counting objects: 1133, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 1133 (delta 0), reused 0 (delta 0), pack-reused 1127
Receiving objects: 100% (1133/1133), 186.80 KiB | 0 bytes/s, done.
Resolving deltas: 100% (874/874), done.
Checking connectivity... done.
root@nate:/var/www/project/lib# cd ..
root@nate:/var/www/project# cp lib/myallocator-pms-php/src/example_autoload.php .
root@nate:/var/www/project# v example_autoload.php

将 example_autoload.php 中的第 33 行的 require_once 自动加载编辑为

require_once(dirname(__FILE__) . '/lib/myallocator-pms-php/src/MyAllocator.php');

运行 HelloWorld ping myallocator

root@nate:/var/www/project# php example_autoload.php
{"Auth" : "true", hello" : "world"}

简单用法示例

可在 myallocator-pms-php/src/example_autoload.php 中找到。您可能需要根据上述示例修改自动加载的 require 路径。

一旦配置了 src/MyAllocator/Config/Config.php，则无需 setConfig。

配置

默认配置文件位于 src/MyAllocator/Config/Config.php。以下是可以配置的内容

paramValidationEnabled

SDK 支持数组、JSON 数据格式参数验证，这可以通过 src/MyAllocator/Config/Config.php 中的 paramValidationEnabled 配置进行配置。如果您希望为了性能或其他原因发送原始请求，则将此配置设置为 false。如果启用参数验证

每个 API 类中的 $keys 数组定义了必需和可选的 API 密钥。
在向 myallocator 发送请求之前，会验证顶层必需和可选密钥。
如果缺少必需的密钥，则抛出 ApiException。
未在 $keys 中定义的顶层键从参数中删除。
强制执行最小可选参数。

dataFormat

该SDK支持三种数据输入/输出格式（数组、JSON、XML），可以通过在src/MyAllocator/Config/Config.php中的dataFormat配置中进行配置。以下表格展示了基于dataFormat配置的请求流程所使用的格式。

you->SDK(dataFormat)    SDK->MA     MA->SDK     SDK->you
--------------------    -------     -------     --------
array                   json        json        array
json                    json        json        json
xml                     xml         xml         xml

相对于XML，首选array和json数据格式。

注意，参数验证仅支持数组和JSON数据格式。对于JSON数据验证，必须在验证后对数据进行解码和重新编码。对于XML数据，原始请求发送给myallocator，并将原始响应返回给您。要在Config.php中禁用paramValidationEnabled以跳过参数验证。

dataResponse

定义您希望在API响应中包含哪些数据。响应的'body'、'code'和'headers'键不可配置，并将始终包含在响应中。如果您打算将请求和响应数据本地存储，则每一项数据都可能有用。以下dataResponse数组中的键将导致相关数据在所有响应中返回

1. timeRequest - The time immediately before the request is sent
    to myallocator (from Requestor). timeRequest is returned
    as a DateTime object.
2. timeResponse - The time immediately after the response is
    received from myallocator (from Requestor). timeResponse is
    returned as a DateTime object.
3. request - The exact request data sent from myallocator including
    authentication and provided parameters. The request is returned
    in the configured dataFormat format. Note, for xml, the request
    is stored in the result prior to url encoding.

debugsEnabled

将src/MyAllocator/Config/Config.php中的debugsEnabled设置为true，以在SDK界面中显示请求和响应数据以及API请求的数据传输格式。

API响应格式

成功的请求调用将返回一个包含以下响应结构的数组。默认情况下，返回所有键/值。如果您希望在API响应中不接收请求数据或response['time']，您可以在src/MyAllocator/Config/Config.php中配置dataResponse数组以删除数据。

return array(
    'request' => array(
        'time' => {DateTime Object},
        'body' => {Request body in dataFormat}
    ),
    'response' => array(
        'time' => {DateTime Object},
        'code' => {int},
        'headers' => {string},
        'body' => {Response body in dataFormat}      
    )
);

request['time'] （可选）是一个表示发送请求到myallocator之前的时间的DateTime对象。

request['body'] （可选）是发送给myallocator的请求正文，格式为您的配置数据格式。

response['time'] （可选）是一个表示接收myallocator响应之后的时间的DateTime对象。

response['code']是HTTP响应代码。

response['headers']是HTTP响应头。

response['body']是响应正文。

请求也可能返回在src/MyAllocator/Exception/中定义的任何异常。请确保将API调用包裹在try块中。您可以在异常块中使用在/Exception/MaException.php中定义的getHttpStatus、getHttpBody和getJsonBody方法来获取信息。另外，可以通过调用getState方法来获取异常的状态信息，该方法可以检索到失败点之前的请求状态信息，格式与上述响应结构相同（请求/响应）。例如，如果发生HTTP连接超时异常，您可以通过getState访问请求时间/正文和响应代码/头。

测试

您可以从顶级目录运行phpunit测试。

Run common infra, JSON API, and XML API test cases. This excludes some of the advanced API's. Refer to `phpunit.xml`.
vendor/bin/phpunit --debug

Run JSON API test cases.
vendor/bin/phpunit --debug tests/json

Run XML API test cases.
vendor/bin/phpunit --debug tests/xml

Run common infra test cases.
vendor/bin/phpunit --debug tests/common

注意，存在针对JSON和XML的不同测试套件。

JSON测试使用array数据格式与SDK接口交互。请参阅src/MyAllocator/Config/Config.php。

设置本地环境变量

大多数测试用例使用本地环境变量，如果没有提供则会被跳过。请从您的数据中导出以下本地环境变量，以便与相关测试用例一起使用。

myallocator-pms-php$ cat test/ENVIRONMENT_CREDENTIALS 
#!/bin/bash
export ma_vendorId=xxxxx
export ma_vendorPassword=xxxxx
export ma_userId=xxxxx
export ma_userPassword=xxxxx
export ma_userToken=xxxxx
export ma_propertyId=xxxxx
export ma_PMSUserId=xxxxx
myallocator-pms-php$ source test/ENVIRONMENT_CREDENTIALS

myallocator / myallocator-php-sdk

维护者

详细信息