Guzzle Services

In 2.0, operations without an explicit httpMethod now default to GET. This changes the behavior of getHttpMethod() and toArray(), which will now return 'GET' instead of an empty string.

Important:

• Explicit httpMethod values must be non-empty strings. Passing an empty string or non-string value throws InvalidArgumentException.
• Casing is preserved. Because Guzzle Services 2.0 uses Guzzle PSR-7 3.x, it no longer automatically uppercases methods. If your service expects GET, use uppercase in your service description.

Guzzle Services allows you to build SDK-style clients by defining a service description. This description maps named operations and parameters to HTTP requests and maps responses into result data. This approach is intended for users building an SDK for an API who want to describe operations in arrays rather than manually writing request serializers.

If you only need to send direct HTTP requests without service descriptions, use guzzlehttp/guzzle instead.

Use the defaults option when instantiating a GuzzleClient to provide parameters that should be included in most or all commands (e.g., apiKey, tenantId).

Explicit arguments passed to a specific command will override these defaults.

Requirement: Any default parameter must have a corresponding parameter schema in the Description (either in parameters or via additionalParameters) so the client knows how to validate and serialize it.

use GuzzleHttp//... imports

$guzzleClient = new GuzzleClient(
    $client,
    $description,
    null,
    null,
    null,
    [
        'defaults' => [
            'apiKey' => getenv('EXAMPLE_API_KEY'),
        ],
    ]
);

// The apiKey will be automatically included in this call
$result = $guzzleClient->listUsers();

The command handler stack is distinct from the underlying Guzzle HTTP handler stack. Command middleware wraps commands before they are transformed into HTTP requests. HTTP middleware should be applied to the underlying GuzzleHttp\\ClientInterface instead.

Use the special @http command key to pass request options to the underlying HTTP client's sendAsync() call. The base command client consumes this key and passes its contents as options.

use GuzzleHttp\Command\CommandInterface;

$client->getHandlerStack()->push(function (callable $handler) {
    return function (CommandInterface $command) use ($handler) {
        $command['@http'] = ($command['@http'] ?: []) + [
            'timeout' => 2.0,
        ];

        return $handler($command);
    };
}, 'timeout');

Operation uri values are expanded using guzzlehttp/uri-template.

• URI Variables: Only parameters with location: uri are used for template expansion.
• Query Expansion: Use location: query to append parameters to the query string after expansion, or use URI Template query expressions (like {?filter*}) with location: uri to let the template control the expansion.

Example of query expansion via template:

'operations' => [
    'searchUsers' => [
        'httpMethod' => 'GET',
        'uri' => '/users{?filter*,page}',
        'parameters' => [
            'filter' => ['type' => 'object', 'location' => 'uri'],
            'page' => ['type' => 'integer', 'location' => 'uri'],
        ],
    ],
]

By default, Guzzle Services uses RFC 3986 encoding with PHP-style array indexes (e.g., foo%5B0%5D=bar). If your API requires empty brackets for arrays (e.g., foo%5B%5D=bar), you must provide a custom Serializer to the GuzzleClient using a QueryLocation with a specific serializer configuration.

To remove numeric indexes, pass true to the Rfc3986Serializer constructor.

use GuzzleHttp//... imports

// Create a QueryLocation that uses Rfc3986Serializer with empty brackets enabled
$queryLocation = new QueryLocation('query', new Rfc3986Serializer(true));

// Create a Serializer with the custom query location
$serializer = new Serializer($description, ['query' => $queryLocation]);

// Pass the serializer to the GuzzleClient
$guzzleClient = new GuzzleClient($client, $description, $serializer);

Guzzle Services 1.0 introduced support for Guzzle 6 and PSR-7.

Key Changes:

• Dependencies: Requires PHP 5.5+, guzzlehttp/guzzle 6.2+, and guzzlehttp/command 1.x. If you are on Guzzle 5, stay on 0.6.
• Base URI: Change baseUrl to baseUri in service descriptions.
• Request Locations:
  • Rename postField to formParam.
  • Rename postFile to multipart.
• Custom Logic: Subscriber-based response processing and validation hooks were replaced by Guzzle Command handlers. Move custom logic to command handlers.

// 0.6 to 1.0: Base URI
// 0.6
$description = new Description(['baseUrl' => '...']);
// 1.0
$description = new Description(['baseUri' => '...']);

// 0.6 to 1.0: Request Locations
// 0.6
'location' => 'postField' // becomes
'location' => 'formParam'

// 0.6
'location' => 'postFile' // becomes
'location' => 'multipart'

Guzzle Services 2.0 is a major release that introduces strict types, higher PHP requirements, and updated dependencies.

Key Changes:

• PHP Version: Requires ^7.4 || ^8.0. If you must support PHP 7.2 or 7.3, stay on 1.x.
• Dependencies: Requires Guzzle Command 2.x, Guzzle 8.x, Guzzle PSR-7 3.x, and Guzzle URI Template 2.x.
• Strict Types: The library now uses native PHP type hints. Custom extension points (like parameter filters) must now accept the exact types expected (e.g., a filter expecting a string will throw a TypeError if passed an int).
• Final Classes: Operation, ValidatedDescriptionHandler, and Rfc3986Serializer are now @final. Do not attempt to subclass them; use service description data or middleware composition instead.

Install the package using Composer to build service-description-driven clients on top of guzzlehttp/command.

composer require guzzlehttp/guzzle-services

Models are reusable schemas defined in the top-level models map. A response model must have its type set to object or array. You can use extends to inherit from other models, though nested maps like properties are not deep-merged.

'models' => [
    'baseJsonObject' => [
        'type' => 'object',
        'location' => 'json',
        'additionalProperties' => false,
    ],
    'user' => [
        'extends' => 'baseJsonObject',
        'properties' => [
            'id' => ['type' => 'string'],
            'name' => ['type' => 'string'],
        ],
    ],
]