Stars: 106
Forks: 21
Pull Requests: 33
Issues: 14
Watchers: 14
Last Updated: 2023-05-21 19:10:20
Provides the foundation for building web service clients with Guzzle
License: MIT License
Languages: PHP, Makefile
This library uses Guzzle and provides the foundations to create fully-featured web service clients by abstracting Guzzle HTTP requests and responses into higher-level commands and results. A middleware system, analogous to, but separate from, the one in the HTTP layer may be used to customize client behavior when preparing commands into requests and processing responses into results.
Key-value pair objects representing an operation of a web service. Commands have a name and a set of parameters.
Key-value pair objects representing the processed result of executing an operation of a web service.
This project can be installed using Composer:
composer require guzzlehttp/command
Service Clients are web service clients that implement the
GuzzleHttp\Command\ServiceClientInterface
and use an underlying Guzzle HTTP
client (GuzzleHttp\ClientInterface
) to communicate with the service. Service
clients create and execute commands (GuzzleHttp\Command\CommandInterface
),
which encapsulate operations within the web service, including the operation
name and parameters. This library provides a generic implementation of a service
client: the GuzzleHttp\Command\ServiceClient
class.
The provided service client implementation (GuzzleHttp\Command\ServiceClient
)
can be instantiated by providing the following arguments:
GuzzleHttp\ClientInterface
such as new GuzzleHttp\Client()
.GuzzleHttp\Command\CommandInterface
object and return a
Psr\Http\Message\RequestInterface
object.Psr\Http\Message\ResponseInterface
object and optionally a
Psr\Http\Message\RequestInterface
object, and return a
GuzzleHttp\Command\ResultInterface
object.GuzzleHttp\HandlerStack
), which can be
used to add command-level middleware to the service client.Below is an example configured to send and receive JSON payloads:
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)
);
}
);
Service clients create command objects using the getCommand()
method.
$commandName = 'foo';
$arguments = ['baz' => 'bar'];
$command = $client->getCommand($commandName, $arguments);
After creating a command, you may execute the command using the execute()
method of the client.
$result = $client->execute($command);
The result of executing a command will be an instance of an object implementing
GuzzleHttp\Command\ResultInterface
. Result objects are ArrayAccess
-ible and
contain the data parsed from HTTP response.
Service clients have magic methods that act as shortcuts to executing commands
by name without having to create the Command
object in a separate step
before executing it.
$result = $client->foo(['baz' => 'bar']);
@TODO Add documentation
-Async
suffix for client methods// 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 Add documentation
wait()
-ing on promises.$result = $promise->wait();
echo $result['fizz']; //> 'buzz'
@TODO Add documentation
executeAll()
executeAllAsync()
.fulfilled
, rejected
, concurrency
)Middleware can be added to the service client or underlying HTTP client to
implement additional behavior and customize the Command
-to-Result
and
Request
-to-Response
lifecycles, respectively.
If you discover a security vulnerability within this package, please send an email to [email protected]. All security vulnerabilities will be promptly addressed. Please do not disclose security-related issues publicly until a fix has been announced. Please see Security Policy for more information.
Guzzle is made available under the MIT License (MIT). Please see License File for more information.
Available as part of the Tidelift Subscription
The maintainers of Guzzle and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.