README

零售订单管理软件开发工具包

这是一个PHP实现的零售订单管理API，它隐藏了不必要的细节，例如请求/响应处理和XML解析，以便为远程消息和过程调用提供一个最小化接口。

需要PHP 5.4或更高版本。

与零售订单管理版本1.8.20兼容。

设置

为了获得最佳结果，请通过Composer进行安装。

在composer.json中

"require": {
    "ebayenterprise/retail-order-management": "~1.0"
}

或者使用Composer CLI

php composer.phar require ebayenterprise/retail-order-management:~1.0

有效载荷

有效载荷代表通过SDK发送或接收的数据。

// The payload factory can be used to create any of the
// supported payloads types.
$payloadFactory = new \eBayEnterprise\RetailOrderManagement\Payload\PayloadFactory;
// Instantiate a payload object with the factory by passing
// the full class name of the payload to the factory.
$payload = $payloadFactory
    ->buildPayload('\eBayEnterprise\RetailOrderManagement\Payload\Payment\StoredValueBalanceRequest');

// Payloads can be populated with data by:

// Calling setters for all of the required data.
$payload->setCardNumber('11112222')
    ->setPanIsToken(false)
    ->setRequestId('1234567890')
    ->setPin('5555')
    ->setCurrencyCode('USD');

// Deserializing a serialized set of data.
$payload->deserialize('<StoreValueBalanceRequest>...</StoredValueBalanceRequest>');

// Complete payload can now be validated.
try {
    $payload->validate();
} catch (\eBayEnterprise\RetailOrderManagement\Payload\Exception\InvalidPayload $e) {
    // The payload is invalid. The exception message, $e->getMessage(),
    // will contain details of the validation error.
}

// Serializing a payload will produce an XML representation of the payload.
$payload->serialize();

请求有效载荷

请求有效载荷代表要通过SDK发送的一组数据。

/** @var \eBayEnterprise\RetailOrderManagement\Api\HttpApi $api */
$api;

// Request payloads will be created as necessary by the transport mechanism
// that will be sending the payload.
$payload = $api->getRequestBody();

// The payload should be populated with data necessary to make the call
// using the SDK.

// Payload interfaces expose methods to set data the data piecemeal.
$payload->setCardNumber('11112222')
    ->setPanIsToken(false)
    ->setRequestId('1234567890')
    ->setPin('5555')
    ->setCurrencyCode('USD');

// A serialized payload may also be deserialized to set all of the data
// in the serialization on the payload.
$payload->deserialize('<StoreValueBalanceRequest>...</StoreValueBalanceRequest>');

// Once the payload has been populated, it can be given back to the
// API and sent.
$api->setRequestBody($payload)->send();

回复有效载荷

回复有效载荷代表从SDK检索的一组数据。

// Get the reply payload from the API object, in this case the
// response from an HTTP API call. Assume $httpApi to be an
// \eBayEnterprise\RetailOrderManagment\Api\HttpApi object.
$payload = $httpApi->getResponseBody();

// If a payload was populated by the SDK, it will have been
// validated automatically. Validation can still be done on demand
// if desired.
try {
    $payload->validate();
} catch (\eBayEnterprise\RetailOrderManagement\Payload\Exception\InvalidPayload $e) {
    // The payload is invalid. The exception message, $e->getMessage(),
    // will contain details of the validation errors.
}

// Get methods will be present for any data in the payload.
$payload->getOrderId();
$payload->getCurrencyCode();

子有效载荷

SDK中的大多数有效载荷都是扁平的，所有必要的数据都设置在单个有效载荷对象中。然而，在某些情况下，一个有效载荷将包含额外的嵌套有效载荷。

/** @var \eBayEnterprise\RetailOrderManagment\Payload\OrderEvents\OrderShipped $payload */
$payload;

// Some payloads will contain an iterable of sub-payloads. In this case,
// $loyaltyPrograms will be an interable payload containing a collection
// of loyalty program payloads.
$loyaltyPrograms = $payload->getLoyaltyPrograms();

// The iterable is a complete payload and can be serialized, deserialized and
// validated like any other payload.
$loyaltyPrograms->validate();
$loyaltyPrograms->serialize();
$loyaltyPrograms->deserialize('<LoyaltyPrograms><LoyaltyProgram>...<LoyaltyProgram><LoyaltyProgram>...<LoyaltyProgram></LoyaltyPrograms>');

foreach ($loyaltyPrograms as $program) {
    // The objects in the iterable area also complete payloads.
    $program->validate();
    $program->setAccount('ABCDEFG');
}

// Iterable payloads will always provide a way of getting empty payloads
// that can be added to the iterable.
$loyaltyProgram $loyaltyPrograms->getEmptyLoyaltyProgram();

// Payload can now be filled out and added to the iterable.
$loyaltyProgram->setAccount('XYZ')->setProgram('RewardProgram');
$loyaltyPrograms->attach($loyaltyProgram);

// Sub-payloads may also be used to create a separate container of data
// within a payload or when a set of data cannot be trivially flattened
// into a single payload.
$destination = $payload->getShippingDestination();

// The shipping destination may be a mailing address (shipped to a customer)
// or a store front location (shipped to a retail store).
if ($destination instanceof \eBayEnterprise\RetailOrderManagement\Payload\OrderEvents\IMailingAddress) {
    $destination->getFistName();
    $destination->getLastName();
} elseif ($destination instanceof \eBayEnterprise\RetailOrderManagement\Payload\OrderEvents\IStoreFrontDetails) {
    $destination->getStoreName();
    $destination->getHours();
}

// In both cases, the object returned will still be a complete payload and
// can be treated as such.
$destination->validate();
$destination->deserialize();

HTTP API

HTTP API是用于与Web服务API通信的传输机制。它简化了创建、发送和接收消息有效载荷的过程。

// Use an HttpConfig instance to configure an HttpApi object for a message.
$apiConfig = new \eBayEnterprise\RetailOrderManagement\Api\HttpConfig(
    $apiKey, // authentication token for connecting to the api
    $apiHostname,
    $apiMajorVersion, // major version number of the service
    $apiMinorVersion, // minor version number of the service
    $storeId, // Retail Order Management store identifier
    $service, // type of service to communicate with (e.g. payments)
    $operation, // string representing the operation to be performed (e.g. creditcard/auth)
    $endPointParams = [] // optional, extra parameters for the request.
);
$httpApi = new \eBayEnterprise\RetailOrderManagement\Api\HttpApi($apiConfig);

try {
    // get the request payload for the message.
    $request = $httpApi->getRequestBody();
    // set the payload as the message body and send the request.
    $httpApi->setRequestBody($request)
        ->send();
    $reply = $httpApi->getResponseBody();
    // process response data

} catch (\eBayEnterprise\RetailOrderManagement\Payload\Exception\UnsupportedOperation $e) {
    // Exception may be thrown from: { send, getRequestBody, getResponseBody }
    // Handle the case where the service and operation specified in the configuration has no matching payload.
    print $e->getMessage();

} catch (\eBayEnterprise\RetailOrderManagement\Api\Exception\UnsupportedHttpAction $e) {
    // Exception may be thrown from: { send }
    // handle the case where the http method is configured with an invalid value
    print $e->getMessage();

} catch (\eBayEnterprise\RetailOrderManagement\Api\Exception\NetworkException $e) {
    // Exception may be thrown from: { send }
    // handle the case where the request takes longer than the timeout threshold or if the connection cannot be made or is lost
    print $e->getMessage();

} catch (\eBayEnterprise\RetailOrderManagement\Payload\Exception\InvalidPayload $e) {
    // Exception may be thrown from: { send, getRequestBody, getResponseBody }
    // handle the case where a payload fails validation
    print $e->getMessage();
}

AMQP API

使用AMQP API响应零售订单管理事件的批次。

// Similar to the HttpApi, start with by filling out a configuration object
$apiConfig = new Api\AmqpConfig(
    $connectionType, // string that configures the way the api connects to a queue.
                     // Use '\PhpAmqpLib\Connection\AMQPSSLConnection' to connect using ssl.
                     // Use '\PhpAmqpLib\Connection\AMQPConnection' to connect without ssl.
    $maxMessagesToProcess, // The number of message to process per batch
    $connectionHostname,
    $connectionPort,
    $connectionUsername,
    $connectionPassword,
    $connectionVhost,
    array $connectionContext,
    $connectionInsist,
    $connectionLoginMethod,
    $connectionLocale,
    $connectionTimeout,
    $connectionReadWriteTimeout,
    $queueName,
    // flags
    $queuePassive,
    $queueDurable,
    $queueExclusive,
    $queueAutoDelete,
    $queueNowait
);
$amqpApi = new Api\HttpApi($apiConfig);

// Get a PayloadIterator object in order to process messages.
$payloads = $amqpApi->fetch();

// Use `valid` to control the iteration over the messages. Each call attempts
// to retreive a message. If a message is received it is `ack`ed immediately.
while ($payloads->valid()) {
    try {
        // The AmqpApi does not deserialize payloads as it recieves them.
        // Deserialization happens during the call to PayloadIterator::current().
        $payload = $payloads->current();
    } catch (\eBayEnterprise\RetailOrderManagement\Payload\Exception\Payload $e) {
        // While iterating through the payloads, a Payload exception may be
        // thrown and cause the premature end of the loop unless caught.

        print $e->getMessage();
    }
    // advance the internal pointer to the next payload
    $payloads->next();
}

测试

使用Docker

包含一个fig文件，用于自动化创建和协调Docker容器以安装和运行测试。

使用Fig安装和运行测试

# setup and install
fig run --rm setup
fig run --rm composer install
# run tests
fig run --rm phpunit

有关自动化测试和静态分析的附加命令，请参阅fig.yml。

有关安装和使用的更多信息，请参阅Docker和Fig。

使用Composer本地运行

在Composer安装所有依赖项后，可以从SDK的根目录运行测试。

vendor/bin/phpunit
vendor/bin/phpmd src text phpmd.xml
vendor/bin/phpcs --standard=psr2 src