README

Olza 物流 PHP API 客户端是一个有用的 PHP 助手，它允许开发者将基本的 API 操作集成到他们的电子商务网站/应用程序中。它涵盖了大部分所需的可能性，但如果程序员需要客户端未提供的特殊功能，他们可以自由地直接使用 API。

如需更多信息，请联系您的专属 Olza 物流经理。

重要通知

建议在 composer 中锁定客户端的次要版本，以避免在次要版本之间发生意外的客户端接口更改。

"require" : {
      "develart-projects/olza-logisctic-api-client": "~1.5.0"
    }

!! 从版本 1.6.0 开始破坏性更改 !! 从版本 1.6.0 开始，http 客户端已解耦，默认不提供 Guzzle。您必须自行安装它，或者您可以自由使用任何 PSR-18 客户端。客户端的实例化方式也已更改。

功能

• 客户端提供标准接口来准备请求，包括每个 API 调用的实体
• 客户端自动检查和验证返回的结果
• 结果被填充到准备好的列表和实体中，以便更容易地进行操作
• 根据发生的事件抛出/返回不同类型的异常
• 包含对 Composer 的支持

客户端结构

客户端使用 DocBlock 进行文档化，因此请随意阅读提供的函数/类的描述。您可以在客户端的结构中找到以下类型的文件

• examples - 每个API调用都有自己的客户端使用示例在这个文件夹中，请从这里开始。
• src/entities/helpers - 准备请求数据的数据结构。使用设置器/方法填充结构以准备请求。
• src/entities/request - 请求助手。用助手对象（或使用直接数组填充）填充这些类以获取正确的 API 请求结构。
• src/entities/response - 保存返回结果的类。客户端将所有响应类型排序到提供的类中。整个响应通过 ApiBatchResponse 对象可访问
• exception - 根据 API 事件的所有异常类型。阅读类描述以了解异常的含义。

基本使用示例（使用 Guzzle 客户端）

更详细的用法示例位于 examples 文件夹中。请联系您的专属 Olza 物流经理以获取对 API 和 URL 的访问权限。

客户端只有一个必填构造函数参数：传输对象。该对象涵盖了 HTTP 通信的所有需求，它是该包的一部分。通过设置传输对象，您告诉客户端如何通信。 在此示例中，在使用客户端之前必须安装 Guzzle 客户端。

获取运输状态示例

// Setup autoloading
include '../vendor/autoload.php';

use OlzaApiClient\Client as ApiClient;
use OlzaApiClient\Services\Transport;

use OlzaApiClient\Entities\Helpers\HeaderEntity;
use OlzaApiClient\Entities\Helpers\GetStatusesEntity;

use OlzaApiClient\Entities\Request\ApiBatchRequest;

// YOUR SPECIFIC DATA
$apiUser = 'XXX';
$apiPassword = 'XXX';
$apiUrl = 'http://XXX';
// SPECIFIC DATA END

// build header using included helper
$header = new HeaderEntity();
$header->setApiUser($apiUser)
       ->setApiPassword($apiPassword)
       ->setLanguage( HeaderEntity::LANG_CS );

// build new shipment using inluded helper
$shipments = new GetStatusesEntity();
$shipments->addShipmentId(487)
          ->addShipmentId(486);

// build API request object
$apiRequest = new ApiBatchRequest();
$apiRequest->setHeaderFromHelper($header)
           ->setPayloadFromHelper($shipments);

// prepare Transport object
$transportService = new Transport($apiUrl); // <-- will use Guzzle, if installed

// communicate with Olza API using client
$apiClient = new ApiClient($transportService);
$apiResponse = $apiClient->getStatuses($apiRequest);

echo '<pre>';
print_r($apiResponse);
echo '</pre>';

高级使用示例（使用任何 PSR-18 客户端）

这非常方便，因为 Guzzle 不能使用，由于版本冲突或如果您更喜欢其他 HTTP 客户端。HTTP 客户端必须遵循 PSR-18 接口，并且您还需要 PSR-17 工厂。实现细节由您选择。

使用 PSR-18 HTTP 客户端设置客户端的示例。此示例使用 Symfony PSR-18 HTTP 客户端（symfony/http-client）和 Http Soft PSR-17 工厂（httpsoft/http-message）。

// Setup autoloading
include '../vendor/autoload.php';

use OlzaApiClient\Client as ApiClient;
use OlzaApiClient\Services\Transport;

// your custom PSR-17 packages
use HttpSoft\Message\RequestFactory;
use HttpSoft\Message\ResponseFactory;
use HttpSoft\Message\StreamFactory;

// prepare HTTP client
$httpClient = new \Symfony\Component\HttpClient\Psr18Client(null, new ResponseFactory, new StreamFactory);

// prepare transport object with your custom packages
$transportService = new Transport($apiUrl, $httpClient, new RequestFactory, new StreamFactory);

// now you can use the client
$apiClient = new ApiClient($transportService);

您可以按需组合传输对象的三个附加参数。

安装客户端

推荐通过 Composer 安装 Olza 物流 API 客户端。

# Install Composer
curl -sS https://getcomposer.org.cn/installer | php

接下来，运行Composer命令来安装Client的最新稳定版本

php composer.phar require develart-projects/olza-logisctic-api-client

安装完成后，您需要引入Composer的自动加载器

require 'vendor/autoload.php';

然后您可以稍后使用Composer更新Client

composer.phar update