#myallocator-pms-php
Myallocator PMS PHP SDK (JSON & XML). Property management systems (PMS) can use this SDK to quickly and reliably integrate with the myallocator API to enable distribution for their customers.
Note, this is not the BuildToUs PHP SDK for OTA's. The BuildToUs PHP SDK can be found at https://github.com/MyAllocator/myallocator-ota-php
Myallocator API Version: 201408
Myallocator PHP SDK Documentation [http://myallocator.github.io/myallocator-pms-php-docs/]
Myallocator API Documentation [http://myallocator.github.io/apidocs/]
Myallocator API Integration Guide [https://docs.google.com/document/d/1_OuI0Z6rTkkuA9xxlJUvhXlazJ9w_iqsp1QzIj4gb2U/edit?usp=sharing]
Myallocator [https://www.myallocator.com/]
Myallocator Development Support [[email protected]]
PHP 5.3.2 and later.
Please see http://myallocator.github.io/myallocator-pms-php-docs/ for the complete and up-to-date SDK documentation.
You can install via composer. Add the following to your project's composer.json
.
{
"require": {
"myallocator/myallocator-php-sdk": "1.*"
}
}
Then install via:
composer.phar install
To use the bindings, either use Composer's autoload [https://getcomposer.org/doc/00-intro.md#autoloading]:
require_once('vendor/autoload.php');
Or manually:
require_once('/path/to/vendor/MyAllocator/myallocator-php-sdk/src/MyAllocator.php');
Grab the latest version of the SDK:
git clone https://github.com/MyAllocator/myallocator-pms-php.git
To use the bindings, add the following to a PHP script:
require_once('/path/to/myallocator-php-sdk/src/MyAllocator.php');
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
Edit require_once autoload in example_autoload.php in line 33 to:
require_once(dirname(__FILE__) . '/vendor/autoload.php');
Run HelloWorld ping to 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
Edit require_once autoload in example_autoload.php in line 33 to:
require_once(dirname(__FILE__) . '/lib/myallocator-pms-php/src/MyAllocator.php');
Run HelloWorld ping to myallocator:
root@nate:/var/www/project# php example_autoload.php
{"Auth" : "true", hello" : "world"}
Can be found at myallocator-pms-php/src/example_autoload.php. You may need to modify the autoload require path as shown above.
The setConfig is not required once src/MyAllocator/Config/Config.php
has been configured.
The default configuration file can be found at at src/MyAllocator/Config/Config.php
. The following is configurable:
The SDK supports parameter validation for array and json data formats, which can be configured via the paramValidationEnabled
configuration in src/MyAllocator/Config/Config.php
. If you prefer to send a raw request for performance, or other reasons, set this configuration to false. If parameter validation is enabled:
- Required and optional Api keys are defined via $keys array in each Api class.
- Top level required and optional keys are validated prior to sending a request to myallocator.
- An ApiException is thrown if a required key is not present.
- Top level keys not defined in $keys are stripped from parameters.
- Minimum optional parameters are enforced.
The SDK supports three data in/out formats (array, json, xml), which can be configured via the dataFormat
configuration in src/MyAllocator/Config/Config.php
. The following table illustrates the formats used for the request flow based on dataFormat.
you->SDK(dataFormat) SDK->MA MA->SDK SDK->you
-------------------- ------- ------- --------
array json json array
json json json json
xml xml xml xml
array
and json
data formats are preferred vs. xml
.
Note, parameter validation only supports array and json data formats. For json data validation, the data must be decoded and re-encoded after validation. For xml data, the raw request is sent to myallocator and raw response returned to you. Disable paramValidationEnabled
in Config.php to skip parameter validation.
Define what data you prefer to be included in Api responses. The response 'body', 'code', and 'headers' keys are not configurable and will always be included in a response. Each piece of data may be useful if you intend to store request and response data locally. The following keys in the dataResponse array below will cause the related data to be returned in all responses:
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.
Set debugsEnabled
to true in src/MyAllocator/Config/Config.php
to display request and response data in the SDK interface and API transfer data formats for an API request.
A successful request call will return an array with the following response structure. By default, all key/values are returned. If you prefer to not receive request data or response['time'] in an Api response, you may configure the dataResponse array in src/MyAllocator/Config/Config.php
to remove the data.
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']
(optional) is a DateTime object representing the time immediately before sending the request to myallocator.
request['body']
(optional) is the request body sent to myallocator in your configured dataFormat.
response['time']
(optional) is a DateTime object representing the time immediately after receiving the response from myallocator.
response['code']
is the HTTP response code.
response['headers']
are the HTTP response headers.
response['body']
is the response body.
Requests may also return any of the exceptions defined in src/MyAllocator/Exception/
. Be sure to wrap your API calls in try blocks. You may use the getHttpStatus
, getHttpBody
, and getJsonBody
methods defined in /Exception/MaException.php
within an exception block for information. Additionally, the getState
method may be called for an exception to retrieve the state information for the request up to the point of failure in the same format as the response structure above (request/response). For example, if an HTTP connection timeout exception occurs, you may access the request time/body and response code/headers via getState
.
You can run phpunit tests from the top directory:
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
Note, there is a different set of tests for json and XML.
The json tests use the array
dataFormat to interface with the SDK. Refer to src/MyAllocator/Config/Config.php
.
Most of the test cases use local environment variables and will be skipped if not provided. Export the following local environment variables from your data to use with the related test cases:
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