README

一个易于使用的 PHP 客户端，用于 Speedy REST API

Speedy 客户端是一个符合 PSR-7 和 PSR-18 的 HTTP 客户端，实现了 Speedy 通信协议。它拥有简洁且一致的 API，经过全面单元测试，并提供了一个示例应用程序以帮助您入门。

功能

此库符合 PSR-7: HTTP 消息接口、PSR-17: HTTP 工厂 和 PSR-18: HTTP 客户端

安装

使用 Composer

$ composer require vasildakov/speedy

使用方法

配置

假设您正在使用 PHP dotenv 从名为 .env 的文件中加载环境变量。在这种情况下，您需要添加以下变量

SPEEDY_USERNAME="username"
SPEEDY_PASSWORD="password"
SPEEDY_LANGUAGE="EN"

下一步是创建一个新的配置实例，如下面的示例所示

<?php

// configuration
$configuration = new Configuration(
    username: $_ENV['SPEEDY_USERNAME'],
    password: $_ENV['SPEEDY_PASSWORD'],
    language: $_ENV['SPEEDY_LANGUAGE']
);

配置 Speedy 客户端

最后一步是配置 Speedy 客户端。客户端可以使用任何 PSR-18 HTTP 客户端 和 PSR-17 HTTP 工厂

使用 Guzzle 和 Laminas Diactoros 的示例

<?php

use GuzzleHttp\Client;
use Laminas\Diactoros\RequestFactory;

$client  = new Client(); // PSR-18 HTTP Client
$factory = new RequestFactory(); // PSR-17 HTTP Factory
$speedy  = new Speedy($configuration, $client, $factory);

使用 Symfony HTTP 客户端 和 Nyholm HTTP 工厂 的示例

<?php

use Nyholm\Psr7\Factory\Psr17Factory;
use Symfony\Component\HttpClient\Psr18Client;

$client  = new Psr18Client(); // PSR-18 HTTP Client
$factory = new Psr17Factory(); // PSR-17 HTTP Factory
$speedy  = new Speedy($configuration, $client, $factory);

发送请求

配置好客户端后，您可以开始发送第一个请求。默认情况下，每个方法都返回 JSON 格式的数据，这些数据可以作为简单的 PHP 数组使用，也可以反序列化为 PHP 模型。

<?php

// use an array
$request = new GetContractClientsRequest(clientSystemId: "1234567");
$json = $speedy->getContractClient($request);
$array = json_decode($json, true);

处理响应

客户端 API 总是返回从端点收到的原始 JSON 响应。可以将其直接使用，解码为 PHP 关联数组，或反序列化为模型对象。

反序列化可以通过两种不同的方式实现：1) 使用序列化器，2) 通过使用 SpeedyModelDecorator 装饰原始 Speedy 客户端。

使用序列化器

<?php

$json = $speedy->getContractClient($request); # json

$serializer = (new SerializerFactory())(); # JMS\Serializer\SerializerInterface

$response = $serializer->deserialize(
    data: $json, 
    type: GetContractClientsResponse::class, 
    format: 'json'
); # GetContractClientsResponse

您可以通过使用 SpeedyModelDecorator 装饰原始 Speedy 客户端来增强原始 Speedy 客户端，而不是每次都调用序列化器。这种增强使得响应更加方便、可预测且易于使用。

<?php

$decorator = new SpeedyModelDecorator(
    new Speedy($configuration, $client, $factory)
);

/** @var GetContractClientsResponse $response */
$response = $decorator->getContractClient(new GetContractClientsRequest());

使用模型

<?php

// @var ArrayCollection $collection
$collection = $response->getClients();
foreach ($collection as $client) {
    dump($client); # Model\Client
    dump($client->getClientName());
    dump($client->getAddress()); # Model\Address
    dump($client->getAddress()->getSiteName()); # string
    dump($client->getAddress()->getPostcode()); # string 
}

文档

待定

许可证

代码在 MIT 许可证 下发布

Speedy REST API 示例

Speedy Web API 集成