README

此库使用Guzzle，并通过将Guzzle HTTP请求和响应抽象为高级命令和结果来提供创建功能齐全的Web服务客户端的基础。可以用来自定义客户端行为的中间件系统，类似于HTTP层中的系统，但与之分离，可以在将命令准备成请求和将响应处理成结果时使用。

命令

表示Web服务操作的键值对对象。命令有一个名称和一系列参数。

结果

表示执行Web服务操作的处理的键值对对象。

安装

可以使用Composer安装此项目。

composer require guzzlehttp/command

服务客户端

服务客户端是实现了GuzzleHttp\Command\ServiceClientInterface的Web服务客户端，并使用底层的Guzzle HTTP客户端（GuzzleHttp\ClientInterface）与服务进行通信。服务客户端创建并执行命令（GuzzleHttp\Command\CommandInterface），这些命令封装了Web服务中的操作，包括操作名称和参数。此库提供了一个通用的服务客户端实现：GuzzleHttp\Command\ServiceClient类。

创建服务客户端实例

可以通过提供以下参数来实例化提供的服务客户端实现（GuzzleHttp\Command\ServiceClient）：

1. 一个配置完整的Guzzle HTTP客户端，将用于执行底层HTTP请求。即一个实现GuzzleHttp\ClientInterface的对象实例，如new GuzzleHttp\Client()。
2. 一个可调用函数，将命令转换为请求。该函数应接受一个GuzzleHttp\Command\CommandInterface对象，并返回一个Psr\Http\Message\RequestInterface对象。
3. 一个可调用函数，将响应转换为结果。该函数应接受一个Psr\Http\Message\ResponseInterface对象和可选的Psr\Http\Message\RequestInterface对象，并返回一个GuzzleHttp\Command\ResultInterface对象。
4. 可选，一个Guzzle HandlerStack（GuzzleHttp\HandlerStack），可以用于向服务客户端添加命令级中间件。

以下是一个配置示例，用于发送和接收JSON负载

use GuzzleHttp\Command\CommandInterface;
use GuzzleHttp\Command\Result;
use GuzzleHttp\Command\ResultInterface;
use GuzzleHttp\Command\ServiceClient;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\UriTemplate\UriTemplate;
use GuzzleHttp\Utils;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

$client = new ServiceClient(
    new HttpClient(),
    function (CommandInterface $command): RequestInterface {
        return new Request(
            'POST',
            UriTemplate::expand('/{command}', ['command' => $command->getName()]),
            ['Accept' => 'application/json', 'Content-Type' => 'application/json'],
            Utils::jsonEncode($command->toArray())
        );
    },
    function (ResponseInterface $response, RequestInterface $request): ResultInterface {
        return new Result(
            Utils::jsonDecode((string) $response->getBody(), true)
        );
    }
);

执行命令

服务客户端使用getCommand()方法创建命令对象。

$commandName = 'foo';
$arguments = ['baz' => 'bar'];
$command = $client->getCommand($commandName, $arguments);

创建命令后，可以使用客户端的execute()方法执行命令。

$result = $client->execute($command);

执行命令的结果将是一个实现GuzzleHttp\Command\ResultInterface的对象实例。结果对象是ArrayAccess可访问的，并包含从HTTP响应中解析的数据。

服务客户端有魔法方法，可以作为执行命令的快捷方式，而不必在执行之前在单独的步骤中创建Command对象。

$result = $client->foo(['baz' => 'bar']);

异步命令

@TODO 添加文档

• 客户端方法中的-Async后缀
• 承诺

// Create and execute an asynchronous command.
$command = $command = $client->getCommand('foo', ['baz' => 'bar']);
$promise = $client->executeAsync($command);

// Use asynchronous commands with magic methods.
$promise = $client->fooAsync(['baz' => 'bar']);

@TODO 添加文档

• 等待承诺。

$result = $promise->wait();

echo $result['fizz']; //> 'buzz'

并发请求

@TODO 添加文档

• executeAll()
• executeAllAsync().
• 选项（fulfilled，rejected，concurrency）

中间件：扩展客户端

可以将中间件添加到服务客户端或底层HTTP客户端，以实现额外的行为并自定义Command-to-Result和Request-to-Response的生命周期。

安全

如果您在此包中发现安全漏洞，请发送电子邮件至 [email protected]。所有安全漏洞都将得到及时处理。请勿在修复方案发布前公开安全相关问题。更多信息请参阅 安全政策。

许可证

Guzzle 在 MIT 许可证（MIT）下提供。更多信息请参阅 许可证文件。

企业版

作为 Tidelift 订阅的一部分提供

Guzzle 的维护者以及数千个其他包的维护者正在与 Tidelift 合作，为您提供构建应用程序所使用的开源依赖项的商业支持和维护。节省时间、降低风险、提高代码健康度，同时支付您确切使用的依赖项的维护者。了解更多信息 点击这里。